Hottest 6/Hottest 6 (1996)(PDSoft)[!].iso/software/programming/c/shadow/docs/introduction.doc

Text File | 1978-11-24 | 204KB | 4,741 lines

                       Shadow Development Documentation
                            Library Version 5.0

                              By David Navas
                         Updated:  13 Nov 1992

                      Copyright © 1992 by David Navas
                         with help from Karen Lien
                            All Rights Reserved


                                THE PLAN
     Basic Concepts
     History
     Overview
     Resource Tracking
        Dual-pass resource tracking
     System String Constants
     Semaphores
        Intra-Process Locking Integrity
        Counting Semaphores
        Conditional Variables
        Multi-Process Signalling
        Performance Issues
     AvlTrees
        Performance Issues
        Summary
     SLists
     Memory
     OOPL
     Object Oriented
     Object-Orientedness under SHADOW
        Creating Classes
        AttributeTags
        MethodTags
           mtag_defnObject
           mtag_procObject
           mtag_flags
           mtag_threadstat
           mtag_priority
           mtag_method
           mtag_arguments
        ArgumentTags
        CreateInstance
        Wrap-up of Methods
     Patcher Class
     Director Class
     Process Class
     Process and Program Shutdown
     Conclusion


                              BASIC CONCEPTS

          SHADOW is a concurrent-object-oriented addition to AmigaDOS.
     Its principle design goal is to help standardize an extensible
     environment paradigm.  It takes advantage of some of the better
     AmigaDOS facilities (shared memory system, IPC ports, and fast
     context switching) by internally managing much of the inter-task
     communications, resource tracking, and resource allocation.

          Traditional object-oriented systems separate function
     interfaces from internal data structures and manage the allocation
     and access of these structures within objects.  SHADOW takes this
     interface separation one step further by partially uncoupling the
     parameter specification at method invocation from the parameter
     specification of the method implementation.

          Because of this relatively high separation, argument type-
     checking is not implemented under SHADOW.  To implement
     type-checking in a run-time bound environment almost requires
     run-time type-checking.  It was decided that this was too
     expensive a use of computing resources.  Under AmigaOS, there is
     some precedence for this;  for example, it is difficult to type-check
     TagItem strutures.

          While SHADOW's main goal is to provide a unified interface
     for distributed, extensible, multi-threaded computing, there are
     many provisions for speed, this being just one of them.  Other
     examples include callback hooks for method dispatching and attribute
     lookups; if you feel SHADOW's versions are not quite what you want
     in either speed or features or both, you can set these hooks on a
     class-by-class basis.  Additionally, attributes are created in such a
     manner as to provide multiple ways of getting at object instance
     variables -- including (but not limited to) the use of more "normal"
     C-structure dereferencing.  While this type of dereferencing isn't
     guaranteed if you're using someone else's class (or, even, if you
     are subclassed off of someone else's class), it does provide a
     very fast way of getting at attributes, and SHADOW uses it in
     several places within its internal code for the sake of efficiency.


                                   HISTORY

          SHADOW was created to solve the problems which I ran into with
     my first programming project -- JazzBench.  That experience taught
     me that the most important thing in a co-operative multi-program
     environment is flexibility.  You need to be able to change the
     behaviour of EVERYTHING -as- -it- -runs-.  This lesson was the
     principle reason behind the initial design of SHADOW, and the result
     of that principle was the entire WatchedVariable construct. To a
     lesser extent, it was also responsible for Patches.

          However, that was not the only lesson that was learned.  Trying
     to locate governing control within a single server not only created
     bottleneck problems, but also, in the end, either limited or
     complicated the design process for my programs.  What I needed was a
     subsystem which effectively dealt with the concurrency and shared
     resource management problems across a distributed environment.

          The other major subsystems of SHADOW support the increased use
     of more complicated data structures.  Exec lists are very fast at
     some things, but searching and sorting are definitely not their
     strong points.




                                 OVERVIEW

     This introduction is an attempt to acquaint the reader with SHADOW's
     capabilities and limitations, and to introduce the programming
     paradigm it offers to Amiga programmers.

     The number of functions in SHADOW is truly daunting.  However, only a
     very few need to be well-understood in order to program SHADOW
     effectively.  These functions fall into about seven categories, which
     we will take up in turn.  The following is an informal introduction
     to familiarize you with the terminology and the pertinent function
     calls in SHADOW.  Confusing terms can (hopefully) be found in
     Glossary.doc.  If they can't be, please let me know what they are, and
     they will appear in future versions of that documentation file.





                         RESOURCE TRACKING CALLS

          SHADOW gives programmers the ability to track resources, and
     in fact forces them to do so.  Objects are NEVER freed until the
     useCount drops to zero.  Objects are often returned from functions
     as Use()'d, meaning that the programmer needs to specifically tell
     the computer when the resource is no longer needed.

     Consider the following example:

          /*
           * Find an object inside of an avltree.
           */
          myobject = FindTreeStringNode(avltree, MY_OBJECT_NAME);
          .
          .
          .

          In this example, a resource that was stored under the
     "MY_OBJECT_NAME" is looked up in a tree and returned to a program.
     Remember that SHADOW is primarily a tool for inter-process sharing
     of objects.  At any time, some other program might come along,
     remove your object from your avltree and try and destroy (free)
     that object.  To prevent this from happening, the FindTreeNode()
     code (on top of which the FindTreeStringNode() code is written)
     returns the object it finds "UseObject()'d", so that some other
     program cannot pull the object out from under you.  It falls to you,
     the programmer, to tell the system when you are done using the
     returned object.

          /*
           * Find an object inside of an avltree.
           */
          myobject = FindTreeStringNode(avltree, MY_OBJECT_NAME);
          .
          . <<Read/modify the object>>
          .
          DropObject(myobject); /* No longer interested in myobject */

     After the DropObject() call, the myobject pointer should be
     considered invalid, and never used thereafter.

          There are several variations on this theme.  The examples we
     will cover are as follows:
          1) Returning objects implies that you must have a a valid
              use()d pointer already, and that the function you return
              to handles the resouce-tracking DropObject() call properly.
          2) Functions declared as returning void * may, in fact, return
              objects that require them to be resouce tracked.
          3) Some functions "swallow" resources.  DropObject() is one
              example, but there are others.


          Consider the example code above.  Imagine if, instead of
     performing all reads and modifications on the objects between
     the FindTreeStringNode() code and the DropObject() code, we wished
     to return the object to a calling function for further processing:

          DoSomething()
          {
             OBJECT myobject;

             /*
              * First retrieve and preprocess the object in some
              * manner, then return to me for further processing.
              */
             myobject = getMyLocalObject();
             .
             . <<Read/modify the object a bit here>>
             .
             DropObject(myobject); /* No longer interested */
          }

          .
          .
          .

          OBJECT getMyLocalObject()
          {
             OBJECT myobj;

             /*
              * Find an object inside of an avltree.
              */
             myobj = FindTreeStringNode(avltree, MY_OBJECT_NAME);
             .
             . <<Read/modify the object>>
             .
             return myobj;
          }


     Notice that getMyLocalObject() does NOT call DropObject() on myobj.
     This is because the resource is still needed when it is returned
     from getMyLocalObject().  The object is truly no longer needed
     only when it is no longer referred to within a sequence of execution.
     Thus, it is DoSomething() that actually calls DropObject(), and not
     getMyLocalObject().

          Now consider the DoShadow() call.  It is prototyped as returning
     a "void *".  Surely many method calls will return other types of data!
     Methods may returns strings, numbers, pointers to structures, objects,
     etc.  It is this last case that we are interested in.

          DoSomething()
          {
             OBJECT myobject;

             /*
              * First retrieve and preprocess the object in some
              * manner, then return to me for further processing.
              */
             myobject = DoShadow(controlObject,
                                 NULL,
                                 METH_GET_LOCAL_OBJECT,
                                 METHOD_END);
             .
             . <<Read/modify the object a bit here>>
             .
             DropObject(myobject); /* No longer interested */
          }

          .
          .
          .

          /*
           * The method declaration (in part).
           */
          ARG_TAG   REF_getMyLocalObject[] = {RET_OBJ};

          OBJECT getMyLocalObject(METHOD_ARGS)
          {
             OBJECT myobj;

             /*
              * Find an object inside of an avltree.
              */
             myobj = FindTreeStringNode(avltree, MY_OBJECT_NAME);
             .
             . <<Read/modify the object>>
             .
             return myobj;
          }

     The method declaration almost exactly parallels the function
     declaration, except that there is an extra ARG_TAG which
     describes what the method expects as arguments and what the method
     returns.

          This method declaration will work for any kind of method call.
     Consider a method invoked synchronously across processes.  The
     method does not drop one from the usecount of the object and instead
     passes the object pointer back to the calling process.  The calling
     process then calls DropObject().  You can see that the resource is
     effectively transferred from one process to another (although that
     procedure is not currently recorded anywhere within these processes).

          Consider the asynchronous case.  While invoking this method
     asynchronously is of little to no value, it can happen under
     certain error conditions (for instance, if you are invoking a
     synchronous inter-process method from a process without an associated
     SHADOW process object).  In this case, the ARG_TAG informs the
     method parsing routines (ParseShadowMessage()) to properly discard
     the returned object.  The DoShadow() method invocation returns
     NULL (as with all asynchronous method invocations).  DropObject()
     correctly handles the NULL input, however your Read/modify code needs
     to handle this case as well!

          One more example of the method invocation is included for
     completeness.  Let's say you had a window class that you were
     creating on top of the included ROOT_CLASS.  The METH_INIT
     method returns a window object which is not only "Use()d" in the
     local sequence of execution sense, but is also placed on various
     system lists.

          OBJECT WinInitMethod(METHOD_ARGS, <window-args>);
          {
             /*
              * Some window initialization.
              */

             SetMethodEnd(...);    /* Set the METHOD_END in the
                                      function's argument stack
                                      correctly for the superclass'
                                      method. */

             return CallSuper();
          }

     Thus when you call CreateInstance()...:

          windowObj = CreateInstance(NULL, WINDOW_CLASS,
                                           META_CLASS,
                                           <window-args>
                                           METHOD_END);

          .
          .
          .

     ...you will eventually need to both tell the system not to "use"
     windowObj locally, AND not to use the windowObj anywhere in the
     system lists.

          .
          .
          .
          /*
           * No longer need windowObj locally.
           */
          DropObject(windowObj);

          .
          .
          .

          /*
           * Cleanup code!
           */
          windowObj = getMyLocalWindow();
          RemoveObject(windowObj);


          RemoveObject() is a linked library call which serves as a
     convenient combination of two function calls.  First, a
     METH_REMOVE is sent to the passed object.  This informs the
     system to Remove the object from all system lists (for more
     details on METH_REMOVE, see below).  The windowObj is then
     passed to the DropObject() function, which removes the
     object from the local sequence of execution.  Thus, when
     RemoveObject() returns, the windowObj is no longer a valid
     window pointer, in exactly the same way that it wouldn't be
     valid if passed to DropObject().

          RemoveObject() is an example of a function which
     "swallows" an object pointer from the local sequence of execution.
     DropObject() is an example as well.  Another example is the
     convenience function SetObject() which transfers ownership of the
     passed object from the local sequence of execution to a shared
     section of memory and returns the object that used to be at that
     memory location back to the program in an atomic fashion.

     If, at anytime, you want to retain a local pointer to the object
     that you pass into one of these functions, you may use the code as in
     the following examples:

          RemoveObject(UseObject(windowObj);

               -or-

          oldObject = SetObject(&memoryLocation, UseObject(newObject));

     UseObject() increases the usecount of the pointer (and also returns
     the pointer to the object, which allows for the easy, if slightly
     confusing, nesting).  At some later point you will have to
     remember to DropObject() the objects, of course!

     The following, slightly less confusing, examples do the same thing:

          UseObject(windowObj);
          RemoveObject(windowObj);

               -or-

          windowObj = UseObject(windowObj);
          RemoveObject(windowObj);

               -or-

          newObject = UseObject(newObject);
          oldObject = SetObject(&memoryLocation, newObject);

          etc.


          In addition to the UseObject() and DropObject() calls for
     SHADOW's objects, there are analogous functions for string
     constants.  These string constants, herein referred to as either
     system strings or unique strings, will now be discussed.  The
     pertinent calls to resource tracking are UseString() and DropString(),
     which perform reasonably analogously to UseObject() and DropObject().


     DUAL-PASS RESOURCE TRACKING

          The distinction between DropObject()ing a resource and
     RemoveObject()ing is more significant than you might suspect at
     first glance.  The main problem with using useCounts in any
     system is the possibility of a self-referencing object, or
     a self-referencing chain of objects.  That is, object1
     contains a field which points to object1 -- in which case
     the useCount will never drop to zero; or object1 contains a
     pointer to object2 that contains a pointer to object3 that contains
     a pointer back to object1.  All three objects' useCounts, in this
     case, will never fall to zero.

          To avoid this problem, SHADOW objects should use the following
     dual-pass algorithm:
          1) In the METH_REMOVE method for each object, all references to
             other objects should either disappear, or be guaranteed to
             never participate in a self-referencing "ring".
          2) After a METH_REMOVE method is received by an object, it
             must never CREATE or allow the creation of, a
             self-referencing "ring" in which it is a participant.
          3) When a METH_DESTROY is sent, the object should be destroyed.

          Self-referencing may occur, therefore, only between the
          METH_INIT call to an object, and the METH_REMOVE call.

          This allows self-referencing to exist within your programs, but
     defines a procedure for eliminating all of these self-references
     without resorting to something time-consuming like garbage
     collection.  The METH_REMOVE pass is often referred to as the
     first pass in the dual-pass resource tracking algorithm, and the
     METH_DESTROY is often referred to as the second pass in the dual-
     pass resource tracking algorithm.  It is up to the individual
     programmer to design his or her classes to conform to these
     specifications.

          Nearly all of the above refers to the GLOBAL resource tracking
     facilities of SHADOW.  SHADOW also provides a LOCAL resource tracking
     facility, which helps to reduce the clean-up code (at the expense of
     some init code).  When a resource is allocated that you want to be
     freed when the process exits, you can pass a pointer to the object
     (must be a SHADOW object!) to the AddAutoResource().
     AddAutoResource() is another example of a procedure that "swallows"
     a resource.

          If that resource is later sent a METH_REMOVE by your program
     before the program actually exits, you should remove the reference
     to it within the program with RemoveAutoResource().  Please see the
     AutoDocs for more details.  The example code may also be helpful,
     although not all of it relies on auto-tracked resources.

          When the METH_REMOVE method is sent to your program's process
     object, all local resources that were added (via AddAutoResource())
     are sent a METH_REMOVE, and are then freed from the process' resource
     tree.  The RemoveCurrentProgram() sends a METH_REMOVE to
     your program's process, for example.


                        SYSTEM STRING CONSTANTS

          SHADOW uses the concept of unique strings as borrowed from the
     NeXT platform.  Each string is assigned a unique address by the
     system.  Two or more strings of the same contents have the same
     system address.  This allows the system to find strings faster --
     by comparing the address, rather than the contents.

          The implementation is via the UseString/DropString/FindString
     library functions, as well as the QuickUseString and QuickDropString
     functions.  System strings are stored on a 1024 entry hash table
     where collisions are linked by a sorted binary tree.  This table is
     found in ShadowBase->sb_systemStrings.

          UseString() will lookup the passed string in the table.  If it
     does not find it, the string is created and stored into the table.
     Otherwise, the object's usecount of the located system string is
     incremented.  The system string's address is then returned.

          DropString() will lookup the passed string in the table, and,
     if found, the string's useCount is decremented.  If the usecount has
     dropped to zero, the string object is freed and removed from the
     system string list.

          FindString() returns the address of a requested system string,
     if one can be found.  It will not increment the usecount, and
     therefore should only be used as an address, rather than as an
     actual string pointer, as that string may go away unexpectedly
     at any time.

          QuickUseString() and QuickDropString() take known system string
     addresses and manually increments or decrements the usecount.  If
     the usecount drops to zero, the normal DropString() is used to
     remove the string from the system.  Be sure that you actually
     have a system string pointer before claling these functions!  These
     functions exist for performance reasons only.  It is preferrable
     to go through the UseString() and DropString() calls instead.

          Consider the following:

               struct StringData {
                    char *sd_name;
                    ULONG sd_data;
               };
               struct StringData MyArray[] = {UseString(-blah-), 1,
                                              UseString(-blah-), 2,
                                              etc.};



     We can now qsort the array on the sd_name field and lookups can be
     as fast as calling a radix search function!

          /*
           * Look up item in qsort()'d MyArray
           *
           * [You can find a decent Radix_Search function in nearly
           *  every computer algorithms textbook.]
           */
          Radix_Search(&MyArray, 0,
                       sizeof(MyArray)/sizeof(struct StringData),
                       UseString(look_for_this_string));
          DropString(look_for_this_string);

          .
          .
          .

          /*
           * free all the strings.
           * Clean up!
           */
          for(i = 0; i < sizeof(MyArray)/sizeof(struct StringData), i++)
               DropString(MyArray[i].sd_name);


     Not only does this improve access by making an O(n) process into an
     O(log n) one, but the entire string compare overhead is eliminated
     by calling UseString() once (instead of strcmp() 'n' times)!

     System strings are used extensively by the object-oriented subsystem
     for such things as lookups of methods and attributes, and for passing
     strings ('JSTR's) between processes during asynchronous method calls.
     They are also used by the AVL tree subsystem which will be covered
     just as soon as we treat the semaphore subsystem.



                              SEMAPHORES

     This discussion of SHADOW's semaphores closely follows the
     RKM:Libraries Third Edition's discussion of Exec's semaphores.  It is
     assumed in this section that you have either read this chapter or
     learned about Exec semaphores from some other source, and that you
     understand the principle concepts behind semaphores.

     Understanding semaphores is a prerequisite to understanding a lot of
     the deeper issues within SHADOW.  This is why I treat it very close
     to the beginning of this introduction.  If you do not understand
     semaphores, it is highly recommended that you either buy the
     RKM:Libraries book, or some general purpose Operating Systems
     textbook.

     Like Exec's semaphoring system, SHADOW's semaphoring system contains
     the basic Shared and Exclusive access constructs.  Under Exec, the
     following calls provide these access constructs:
          AttemptSemaphore(<semaphore>)
          ObtainSemaphore(<semaphore>)
          ObtainSemaphoreShared(<semaphore>)
          ReleaseSemaphore(<semaphore>)

     The analogous calls in SHADOW are as follows:
          PSem(<address>, SSEM_ATTEMPT | SSEM_LOCK);
          PSem(<address>, SSEM_LOCK);
          PSem(<address>, SSEM_READ);
          VSem(<address>);

     Using the macros defined in <shadow/semaphore.h> these become:
          PSem(<address>, SSEM_ATTEMPT | SSEM_LOCK);
          RWLock(<address>);
          ReadLock(<address>);
          VSem(<address>);


          However, unlike Exec's semaphoring system, SHADOW does not have
     calls that are directly analogous to the AddSemaphore(),
     RemSemaphore(), FindSemaphore() and InitSemaphore() library calls of
     Exec.  Instead, SHADOW allows you to semaphore any arbitrary address
     (excepting (void *)-1 which is reserved).  The contents at this
     address do not participate in the semaphoring process.  This implies
     that there are no SHADOW semaphore structures analogous to Exec's
     SignalSemaphores. Instead, all legal addresses act as global
     semaphore points.  SHADOW takes care of creating, initializing, and
     destroying all structures needed to internally manage the semaphoring
     process, and because the Amiga's address space is linear across all
     processes, all semaphores are global by nature.  This eliminates the
     need for the AddSemaphore(), the RemSemaphore(), the FindSemaphore(),
     and the InitSemaphore() calls, thus simplifying the programmer's
     task.

     Consider two threads running through the following program, one at
     Reader(), one at Writer().

          UBYTE *ASharedString;

          Reader()
          {
             while(TRUE)
             {
                ReadLock(ASharedString);
                printf("The string %s\n", ASharedString);
                VSem(ASharedString);
             }
          }

          Writer()
          {
             while(TRUE)
             {
               WriteLock(ASharedString);
               gets(ASharedString);
               VSem(ASharedString);
             }
          }

     "ASharedString" acts as a shared string between the Reader() and
     Writer() threads.  To coordinate access to the string, the
     address of the string is also used as the semaphoring address
     point.  while this is the most straightforward way of managing the
     semaphore system, there is nothing wrong with creating an arbitrary
     semaphoring address point.  For example, you might arbitrate access
     for the string by semaphoring against the Reader()'s function address!

          UBYTE *ASharedString;

          Reader()
          {
             while(TRUE)
             {
                ReadLock((void *)Reader);
                printf("The string %s\n", ASharedString);
                VSem((void *)Reader);
             }
          }

          Writer()
          {
             while(TRUE)
             {
               WriteLock((void *)Reader);
               gets(ASharedString);
               VSem((void *)Reader);
             }
          }

     One warning, however.  You are not allowed to semaphore on an address
     that you do not in some way possess.  This is to guard against the
     possibility that some other process gets started that actually -does-
     use this address.  Because SHADOW's semaphoring points are
     automatically public, when this other process attempts to semaphore
     against its address it will come into conflict with your programs.
     This is potentially deadly.

     As a corollary, you must release all semaphores that you obtained
     before your program exits and/or before the address that the
     semaphore is arbitrating is freed back to Exec's memory pools.
     To aid in testing, you are directed to the sb_semTree field
     within ShadowBase which acts as the base of all semaphore allocations
     that SHADOW makes.  This field is zero when there are no outstanding
     semaphores.


          In addition to not having the complications of semaphore
     structures and the (unnecessary, on the Amiga) distinction between
     global and local semaphores, SHADOW does not offer Exec's prepackaged
     ObtainSemaphoreList() and ReleaseSemaphoreList().  While these calls
     are sometimes important to use to avoid deadlock situations, it
     is entirely possible to build your own SemaphoreList wrappers by
     clever use of the SSEM_ATTEMPT flag.  This is left as the proverbial
     exercise to the reader.

          Instead, SHADOW expands on Exec's usage of semaphores to
     include intra-process locking integrity, counting semaphores,
     conditional variables, and multi-process signalling.  We take each
     one in turn, and then address performance issues.


     Intra-Process Locking Integrity

          This may be a confusing amalgamation, but the concept is simple.
     Take an example of a library function IterateList().  The purpose
     of IterateList() is to call a function on each of the members on
     a shared list.  We might implement this as follows:

          IterateList(struct MyList *list, void (*func)(struct MyNode *node))
          {
               struct MyNode *node;

               PSem(list, SSEM_READ);
               node = list->first;
               while(node)
               {
                    func(node);
                    node = node->next;
               }
               VSem(list);
          }

     Consider, however, what might happen if we pass a function which
     removed the node from the list it was in.  Clearly this would have
     very bad consequences for IterateList()!

     Therefore, instead of the normal Exclusive/Shared access locks,
     SHADOW provides three types of access locks -- an SSEM_READ,
     an SSEM_WRITE, and an SSEM_LOCK (a read-write lock).  SSEM_READ
     locks are shareable across processes and are nestable within
     processes.  SSEM_WRITE is neither shareable nor nestable.  SSEM_LOCK
     is not shareable, but is nestable -- with the following modifications:

        a) Multiple SSEM_LOCK requests always nest.
        b) If you request an SSEM_READ on an SSEM_LOCKed semaphore,
             the semaphore becomes a nestable, non-shareable,
             SSEM_READ semaphore.  The semaphore reverts to its earlier
             Read-Write status upon execution of the matching VSem() call.
        c) If you request an SSEM_WRITE on an SSEM_LOCKed semaphore,
             the semaphore becomes a non-nestable, non-shareable,
             SSEM_WRITE semaphore.  Again, the semaphore reverts
             to its earlier Read-Write status upon the matching
             VSem() call.

     It is easier to understand this nesting ability by focusing on the
     Read/Write characteristics of these different locks, rather than
     on their Shared/Nestable characteristics.

     Any number of processes can Read.  Only one process may Write, and
     no one may be Reading at the time.  The Read-Write is used for
     mutual exclusion across processes and can become either a Read-only
     or a Write-only semaphore as needed -- although the semaphore will
     always remain non-shareable until the last Read-Write semaphore
     access has been released via VSem().

     Consider the following example taken from the RemoveResources()
     function in SHADOW:

          .
          .
          .
          PSem(&tree, SSEM_LOCK);
          DoInOrderTree(&tree, RemoveCompInstance, NULL);
          FreeTreeAllNodes(&tree);
          VSem(&tree);
          .
          .
          .

     Here we are attempting to eliminate each node from a tree and invoke
     the METH_REMOVE method on each node (object) on the tree.  Because of
     the organization of the AVLTree functions (described below), this is
     a two stage process -- we invoke the METH_REMOVEs on all objects in
     the tree (DoInOrderTree()), and then remove all objects from the
     tree (FreeTreeAllNodes()).

     As in the above list example, the DoInOrderTree() library function
     locks the tree with an SSEM_READ semaphore call.  The
     FreeTreeAllNodes(), on the other hand, locks the tree with an
     SSEM_WRITE semaphore.

     In order to be truly safe, we need to ensure that no other process
     adds a node between the DoInOrderTree() call and the
     FreeTreeAllNodes() call where the tree would normally be accessible.
     To accomplish this, we get an SSEM_LOCK semaphore to surround the two
     function calls.  The SSEM_LOCK provides the nesting that is needed by
     the two library functions which acquire their own semaphores, while
     maintaining the exclusive access characteristics required by the code.

     In addition, because SSEM_READ/SSEM_LOCK nesting is different
     from SSEM_LOCK/SSEM_LOCK nesting, the intra-process locking integrity
     is maintained.  Any attempt to gain write or read-write access to the
     tree from within the DoInOrderTree() call will halt the program, and
     any attempt to lock the tree at all within the FreeTreeAllNodes()
     will halt the program.  This allows the programmer to debug the
     problem when it occurs, instead of trying to deduce what occurred
     from problems which might have normally ensued.

     Compare that to the alternative as suggested by V39Beta Exec
     semaphores.  Not only does Exec fail to make a distinction
     between Write and Read-Write semaphores, but when you request
     a shared semaphore on a semaphore that you already have locked
     exclusively, you get another exclusive access granted!  This
     precludes the potential debugging advantages of SHADOW's semaphores.

     [Of course, it's even worse when you consider that V37 semaphores
      did something entirely different under this exact same set of
      circumstances anyway....]


     Counting Semaphores

     Counting Semaphores are a very straightforward addition to most
     semaphoring systems.  A typical example is with resource
     allocations.  Consider the problem of an audio.device type interface
     where you have four available channels.  All four channels are
     allocated, and a program is waiting for any two.

     Here is where counting semaphores come in.  You create a
     counting semaphore by using the CreateSemaphore() macro, passing
     in the maximum number of available resources.  It returns the
     semaphoring address point that you can use in the rest of
     your calls.  You should later free this count semaphore by
     calling DestroySemaphore(), passing in the same address as
     was returned by CreateSemaphore.  The ObtainNumber() and
     ReleaseNumber() macros can be used on this address between
     the Create() and Destroy() calls to obtain and release a
     certain number of resources.

          APTR GlobalResourceSemaphore = CreateSemaphore(4);

          .
          .
          .

                                   /* Obtain two channels. */
          ObtainCount(GlobalResourceSemaphore, 2);

          .
          .
          .

                          /* release a channel back to the system */
          ReleaseCount(GlobalResourceSemaphore, 1);

          .
          .
          .

                                   /* Obtain three channels */
          ObtainCount(GlobalResourceSemaphore, 3);

          .
          .
          .

                              /* Prepare to destroy the semaphore */
          DestroySemaphore(GlobalResourceSemaphore);

          /*
           * All resources have been freed, semaphore is now freed
           * as well.
           */
          ReleaseSemaphore(GlobalResourceSemaphore, 4);


     Notice carefully that you can ask for any number of resources --
     if you ask for too many, you may hang indefinitely, and as there
     is no priority to your semaphore requests, starvation is definitely
     possible.
     Also note that the semaphore is not actually freed from the system
     until all processes release their locks and no process is
     waiting on the semaphore, irregardless of the call to
     DestroySemaphore().

     In addition to these calls, you can call the UpCountSem() and
     DownCountSem() macros which create the semaphore automatically
     from the passed address.  This eliminates the need to call the
     CreateSemaphore() and DestroySemaphore() macros, but it limits you
     to single-step increment/decrement calls.


          ULONG SemaphorePoint;


                                   /* Obtain two channels of four. */
          UpCount(&SemaphorePoint, 4);
          UpCount(&SemaphorePoint, 4);

          .
          .
          .

                          /* release a channel back to the system */
          DownCount(&SemaphorePoint);

          .
          .
          .

                                   /* Obtain three channels of four*/
          UpCount(&SemaphorePoint, 4);
          UpCount(&SemaphorePoint, 4);
          UpCount(&SemaphorePoint, 4);


          DownCount(&SemaphorePoint);
          DownCount(&SemaphorePoint);
          DownCount(&SemaphorePoint);
          DownCount(&SemaphorePoint);
          /*
           * All resources have been freed, semaphore is now freed
           * as well (automatically).
           */


     Conditional Variables

     Conditional Variables keep track of the number of "conditions" that
     have occurred.  A task can cause any number of conditions, and can
     wait for any number of conditions.

     Consider the Reader() and Writer() problem above.  Consider what is
     really happening.  It is quite possible for a single string to be
     printed out between zero and -thousands- of times.  In reality, what
     we want is to have each string printed out once.  Here, the Reader()
     and Writer() example becomes the more classic Consumer() and
     Producer() problem.  Here is an example implementation using
     conditional variables:

          extern void Producer(void);

          UBYTE *ASharedString;

          void main(void)
          {
               SetCondition(((char *)Producer) + 1, 1)
                    /*
                     * Default to produce the first string.
                     * We can obviously default to consuming the
                     * first string as well....
                     */

               startpThreads();
          }


          void Consumer(void)
          {
             while(TRUE)
             {
                WaitCondition(((char *)Consumer) + 1, 1);
                    /*
                     * Wait for a new string.
                     */
                printf("The string %s\n", ASharedString);
                    /*
                     * Print the new string
                     */
                SetCondition(((char *)Producer) + 1, 1);
                    /*
                     * The string has been consumed, want another one!
                     */
             }
          }

          void Producer(void)
          {
             while(TRUE)
             {

               WaitCondition(((char *)Producer) + 1, 1);
                    /*
                     * Wait for a need for a new string.
                     */
               gets(ASharedString);
                    /*
                     * Get another string.
                     */
               SetCondition(((char *)Producer) + 1, 1);
                    /*
                     * The string has been produced!
                     */
             }
          }

     This code will work with as many Producer and Consumer threads as
     you like.  Only one condition occurs, so only WaitCondition()
     is satisfied for each SetCondition() call.  Also, the startup
     case assumes that no string is, at first, available.  The code
     would be slightly different without that assumption.

     Also notice that these programs use -odd- addresses for condition
     variables.  This is to avoid potential address collisions.  Most
     lock functions occur at even addresses, so I have all of my
     programs use the odd addresses for conditional varialbes, thereby
     eliminating a potential source of confusing.  There is NO dictum
     that requires you to follow in my footsteps, though.


     Multi-Process Signalling

     Multi-Process Signalling allows an arbitrarily large number of
     programs to find out when something happens.  Where condition
     variables keep track of the number of conditions that occurred
     but haven't been handled, the Multi-Process signalling
     cannot keep track of the number of "outstanding" conditions
     that have occurred.  However, it can wake up EVERYONE
     waiting on the WaitLevel() macro.

          WaitLevel(address); waits for a condition to occur associated
                              with the passed address.

          SetLevel(address);  makes the multi-process signalling
                              condition occur.

     Examples are left as an exercise for the reader.


     Performance Issues

          Considering the extended number of features that SHADOW
     includes, and especially considering that the vast majority of
     semaphores are created and deleted on the fly, it may not be too
     surprising to discover that SHADOW's semaphoring system is slower
     than Exec's.  Indeed, it would be miraculous if it weren't.  What
     is surprising is that SHADOW's semaphores are very competitive with
     Exec's, and if we reduce every exec semaphore access to include a
     FindSemaphore() call (a Find() on a string that is less than four
     byteslong, even), we find that SHADOW's semaphores run at about
     the same speed as Exec's semaphores.

          To be more precise, SHADOW's semaphores have a performance
     overhead of about 2-5x that of Exec's local semaphoring system (that
     is, Exec's semaphores without the overhead of FindSemaphore()) and
     about the same overhead as Exec's global semaphoring system (that is,
     Exec's semaphores with the FindSemaphore() overhead).

          EXEC's global semaphoring system has a frightening overhead when
     either large strings (more than four characters) or large numbers of
     semaphores are used.  For instance, if each string is about sixteen
     characters long instead of four, Exec does only about half as well as
     SHADOW.  Because SHADOW uses addresses as a semaphoring point,
     instead of strings, and because SHADOW stores its semaphores on a
     binary tree, instead of a linked list, SHADOW's overhead grows
     slower than Exec's.  The test cases sited here are performed in the
     included "perftest" program, and uses only 12 semaphores at a time --
     a reasonable figure, it seems to me.

          But what if you want to use SHADOW's semaphores and key the
     semaphores on a string?  Use the PSemString() and VSemString() calls!
     Essentially, the string is UseString()d by the system, and the
     address of the returned string is used as the semaphoring point.
     This allows for both the flexibility of named semaphores, while
     allowing for the speed of unnamed semaphores.

          A good use for named semaphores is for coordinating the startup
     of a program.  Consider what happens if two copies of the same program
     get launched nearly simultaneously.  Because each program defines
     the same classes to the system (usually), it is wise to start each
     program only once, and then merely instantiate another existence
     of the program once started.  This provides the flexibility of
     "resident" programs, without the constant overhead for programs
     that aren't needed.

     Unfortunately, it is difficult to coordinate the simultaneous
     startup of programs.  Browser uses the following code:

        PSemString("Browser Program", SSEM_LOCK);
        /*
         * CreateInstance() only works if the BLOCK_CLASS is already
         * defined (which means that another browser program has been
         * launched).
         *
         * Otherwise, we're the first browser program, and will have to
         * define BLOCK_CLASS, etc.
         */
        if (CreateInstance(NULL, BLOCK_CLASS, META_CLASS, METHOD_END))
        {
           VSemString("Browser Program");
           return;
        }
        .
        . /* define BLOCK_CLASS, etc. */
        .
        VSemString("Browser Program");
        .
        .
        .

     Here we see that if two Browser Programs startup, the code is
     guaranteed to define the BLOCK_CLASS in one program, and then
     instantiate an instance of BLOCK_CLASS in the other.

     --

          Getting back to performance issues, another advantage to SHADOW's
     semaphores is that they take less space than their Exec counterparts,
     first because they don't require the overhead of semaphore-lists, and
     second because the semaphores don't need to exist in memory until
     needed.  It is worth noting that SHADOW will pseudo-busy wait if it
     tries to allocate a semaphore structure but runs out of memory,
     unless, of course, it was passed the SSEM_ATTEMPT flag -- in which
     case it fails.

          So we conclude that while Exec semaphores have some speed
     advantage in the simple cases, they are slower when sharing semaphores
     across more than one program, always take more memory, and are more
     difficult to setup and use.  I definitely recommend the SHADOW
     subsystem over the Exec subsystem, if only for the flexibility that
     it offers unless speed is absolutely crucial.



                                   AVLTREES

          AVL trees are auto-balancing binary trees.  Again, this
     discussion assumes that you have read a decent algorithms book which
     would cover AVL trees.  I suggest "Data Structgures and Program
     Design in C" by Robert L. Kruse, Bruse P. Leung, and Clovis L. Tondo.

          SHADOW's AVL trees are built on top of the semaphore code, the
     memory code (discussed below), the resource tracking code, and, in
     some part, the system string code.  They are designed for quick
     access by many processes and are used to store metas, classes,
     and other instances within SHADOW.  Again, the design goal of SHADOW
     is to provide for multi-threaded computing, so all AVL trees are
     semaphored when accessed by the system.

          To initialize an avl tree:

               AVLTree  bt = NULL;

          Now you can add any number of SHADOW-objects (the definition of
     exactly what a SHADOW-object is is located below) to the binary tree.
     Indeed, you may add any number of objects with any key to any number
     of binary trees.  AVLTrees usually require you to have different
     keys for each inserted item.  SHADOW does not impose this
     restriction.  Exec requires you to have one Node structure for
     each list that an "object" might belong to.  Again, SHADOW does
     not require this.  SHADOW allocates and frees its own BinNodes
     internally when required.  In addition, to support the idea of
     non-unique keys, the RemoveTreeNode() function takes the key AND
     the address of the object you want removed -- if you don't know the
     address of the object, you can find it by calling FindTreeNode()
     with the key.  The first object found with that key will be returned,
     and you may pass this to the RemoveTreeNode() function.

               OBJECT object1 = <>, object2 = <>;

               AddTreeNode(&bt, object1, 12);
               AddTreeNode(&bt, object2, 13);
               /*
                * Note: object1 and object2 have not been swallowed,
                * so swallow them now!
                */
               DropObject(object1);
               DropObject(object2);

               .
               .
               .

               obj = FindTreeNode(&bt, 13);
               /*
                * do something useful with obj!
                */
               DropObject(obj);

               .
               .
               .

               /*
                * Now we remove all of our nodes from the tree.
                */
               obj = FindTreeNode(&bt, 12);
               RemoveTreeNode(&bt, obj, 12);
               DropObject(obj);
               obj = FindTreeNode(&bt, 13);
               RemoveTreeNode(&bt, obj, 13);
               DropObject(obj);

               /*
                * Alternatively, we can call FreeTreeAllNodes()
                * providing we meet the following specifications:
                *
                *   All nodes that were added must have been added to
                *   the tree via the Add*TreeStringNode() functions.
                *
                *   All nodes not added this way must have keys
                *   between 0 and 255 or keys equal to the object's
                *   address  [ie: AddTreeNode(&bt, obj, (ULONG)obj)].
                *
                * FreeTreeAllNodes(&bt);
                *
                * This removes all nodes from the tree and drops all
                * the applicable resources.
                */

     SHADOW provides functions which sort the objects by a string.  Do
     not fool yourself into believing that this produces an object tree
     which is sorted alphabetically -- SHADOW's string routines are built
     around the system strings mentioned above.  Sorting of the nodes
     occurs according to the -address- of the system string, NOT the
     contents of the string itself.

               /*
                * Add some objects keyed on some strings.
                */
               AddTreeStringNode(&bt, object1, "Sort me!");
               AddTreeStringNode(&bt, object2, "Me too!");
               DropObject(object1);
               DropObject(object2);

               .
               .
               .

               /*
                * We now demonstrate both lookups of objects using
                *  a string as a key, and removal of objects from
                *  trees where the object was keyed on a string.
                */
               object1 = FindTreeStringNode(&bt, "Sort me!");
               object2 = FindTreeStringNode(&bt, "Me too!");
               RemoveTreeStringNode(&bt, object1, "Sort me!");
               RemoveTreeStringNode(&bt, object2, "Me too!");
               DropObject(object1);
               DropObject(object2);


     SHADOW also provides a routine which will call a function on each
     node within the bintree -- passing in the node, the key, and a
     value passed into the RecurseTree() function.

               /*
                * Example RecurseTree() callback.
                *
                * Here we are looking for something inside an object
                * that matches the passed "passedIn" variable.
                *
                * We will return the object if found, or NULL to
                * continue looking.
                * The Recurse() function then returns what we
                * return, or NULL if we never return anything.
                */
               void __regargs *myFunc(OBJECT obj, ULONG key,
                                      void *passedIn)
               {
                    struct SomePrivStruct *sps;

                    sps = FindAttribute(obj, ATTR_PRIVATESTUFF);

                    if (sps->sps_searchMe == passedIn)
                         return UseObject(obj);   /* return object used! */

                    return NULL;
               }

               .
               .
               .

               /*
                * Find the object that has the correct info inside it.
                * Search all objects on the binary tree -- we don't
                * particularly care about the order.
                *
                * The number 67 is passed to the myFunc callback as
                * the "passedIn" variable of that function.
                */
               found = RecurseTree(&bt, myFunc, (void *)67,
                                   SHADOW_RECURSE_INORDER);
               .
               .
               .
               DropObject(found);

     Here we have demonstrated a search implemented via the RecurseTree().
     Using this function we can also duplicate an entire tree:

               /*
                * We assume that the binary tree had all of its objects
                * stored according to a system string object.
                * Adjustments would have to be made if this were not so.
                */
               void __regargs *dupStringFunc(OBJECT obj, ULONG key,
                                             AVLTree *passedIn)
               {
                    AddTreeStringNode(passedIn, obj, (char *)key);
                    /*
                     * Remember to return NULL to continue the
                     * recursion!
                     */
                    return NULL;
               }

               .
               .
               .

               /*
                * Duplicate the avl tree.
                * bt gets duplicated onto bt2.  Don't forget to set bt2
                * to NULL to start with!
                */
               bt2 = NULL;
               RecurseTree(&bt, myFunc, &bt2, SHADOW_RECURSE_INORDER);

               /*
                * bt2 now has a direct copy of bt.
                */

               .
               .
               .

               /*
                * Cleanup!
                */
               FreeTreeAllNodes(&bt);
               FreeTreeAllNodes(&bt2);

     There are several different ways to recurse down the binary tree:
               SHADOW_RECURSE_PREORDER
               SHADOW_RECURSE_INORDER
               SHADOW_RECURSE_POSTORDER
               SHADOW_RECURSE_BACKORDER

     PREORDER visits the nodes as Root, left-tree, right-tree.  INORDER
     visits the nodes as left-tree, Root, right-tree -- giving an
     increasing key traversal.  POSTORDER visits the nodes as left-tree,
     Root, right-tree.  BACKORDER visits the nodes as right-tree, Root,
     left-tree -- giving a decreasng key traversal.

     Several macro functions have been provided in much the same way that
     macros are available for many of the different PSem() semaphore calls.
     These are:
               DoPreOrderTree(&bt, func, passedIn)
               DoInOrderTree(&bt, func, passedIn)
               DoPostOrderTree(&bt, func, passedIn)
               DoBackOrderTree(&bt, func, passedIn)

     They directly correspond to the flags of similar name.


     There are several important things to remember when using SHADOW's
     AVL trees.  For one thing, some of the functions assume that the
     nodes are sorted by system string address (FreeTreeAllNodes()),
     and won't be happy if they find out otherwise.  Other functions,
     like RecurseTree() don't care, but the callback functions supplied
     to this call might.

     In addition, it is important to remember that all nodes are sorted
     on unsigned keys, not signed keys.  Also, all objects added to avl
     trees must be SHADOW objects, not some concoction of your own.
     This either means that the first three longwords correspond to the
     struct ClasslessObject definition, or that the object was
     created via a CreateInstance()/CreateSubClass() or equivalent call.


     Performance Issues

     SHADOW's AVL tree functions (apart from the *Watched*() functions
     which are really a part of another subsystem) are implemented in
     assembly.  They are guaranteed to use less than 256 bytes of stack,
     independent of how large the tree grows -- assuming the tree resides
     in a 32bit address space, that is.

     Despite the relatively large overhead implied by the use of SHADOW's
     semaphores, a node can be found in a 256 node tree in an average of
     84 microseconds on my A3000 -- an object stored with a string as
     the key would take slightly longer, depending on the length of the
     string.

     Adding and removing nodes takes slightly longer.  Again, with an
     average of 256 nodes inserted and removed in order, the total
     add-remove cycle takes about 280 microseconds (on the A3000).
     This is not bad, considering that the binary nodes used internally
     by the AVLTree subsystem are allocated and freed as needed.  Exec
     lists, while they do not have this assorted cost, are less flexible
     about how many times an "object" can be added and to how many trees.

     You should pick the storage structure that is best suited for you.
     Fortunately, SHADOW now gives you a choice, without forcing you to
     do your own implementation.


     Summary

     In summary, there are only four really important AVLTREE calls to
     understand:
          AddTreeNode()    adds an object to an AVL tree sorted by a
                            passed key.
          RemoveTreeNode() removes an object from the AVL tree.
          FindTreeNode()   finds the object in an AVL tree, and returns
                            this object.  You should DropObject() that
                            object when you are done using it, as is TRUE
                            of any resource that SHADOW returns to you.
          RecurseTree()    calls a function for every object in the binary
                            tree.

     The other function which is NOT a derivative of these four is
     FreeTreeAllNodes().  It's a pretty esoteric call -- it just removes
     all objects from the AVL tree, though.  Nothing special.  [Note
     the restrictions on its use!]

     All other AVL tree calls are derivatives of the first three calls,
     and four other calls [DoPreOrderTree() for example] are built
     directly on top of RecurseTree() as #defines macros.


                                    SLISTS

          SLISTs are single-linked, prioritized lists.  The salient
     functions are:
          AddSListNode()
          RemoveSListNode()
          FindNodePriInSList()

     Like their SHADOW avltree cousins, these functions are semaphored and
     the objects added into the lists are resource-tracked -- so all
     objects added to these lists MUST be SHADOW-objects.

     The only advantages they add over Exec is the resource tracking, the
     automatic semaphores and the ability for objects to reside in
     multiple lists, multiple numbers of times.  The real disadvantage is
     that there is a great deal of overhead for adding prioritized
     nodes, and removing nodes.

     Use them if you find them useful.



                                    MEMORY

          In this discussion about semaphores and AVLTrees and SLists, we
     have glossed over one consistent point -- memory management.  For
     instance, we know that SHADOW's semaphores have some kind of
     internally managed semaphore object, we know that AVLTrees have some
     kind of internally managed BinNode structures, and we know that
     SLISTs have some kind of internally managed Node structures, but we
     don't know how these structures are allocated and freed.

     SHADOW has a memory subsystem that is responsible for dealing with
     these tasks.  While its main purpose is to create and destroy these
     small structures as fast as possible, it has enough hooks to be
     useful to anyone who has to manage a large number of structures of
     exactly the same size.

     The following are the functions which implement SHADOW's MEMORY
     subsystem:
          result = (BOOL)InitTable(SEMLIST list, allocfunc, freefunc, size)
          memory = (void *)AllocateItem(SEMLIST list)
          (void)FreeItem(SEMLIST list, (void *)memory)
          FreeTable(SEMLIST list)


     You use these memory tables by first calling the InitTable(),
     using the AllocateItem() and FreeItem() calls, and then calling
     FreeTable().

          struct MemoryList globalMemList;

          InitTable(&globalMemList, NULL, NULL, 16);

     This initializes the memory  table to use the default allocation and
     free calls (AllocMem(MEMF_PUBLIC)/FreeMem()).  In addition, it sets
     up the memory table to dole out memory in 16byte chunks, and
     pre-allocates 32 items.

     Each item allocated from the table will be 16bytes long.  The contents
     of the items are not guaranteed to be initialized to zero, EVEN if you
     use your own function callbacks to allocate the memory as MEMF_CLEAR.
     Items are allocated from Exec's memory pools 32chunks at a time.
     When enough items are put back into the table, the table will free
     a full 32chunks back into Exec's free memory pool.  The definition
     of "enough" is purposely left vague.

          memory = AllocateItem(&globalMemList);
          FreeItem(&globalMemList, memory);

     When all allocations are finished and you are done using the memory
     list, call FreeTable().  This frees all the still allocated items
     that you might have left allocated, and it returns all resources
     to Exec's free memory pool.

          memory = AllocateItem(&globalMemList);
          .
          .
          .
          FreeTable(&globalMemList);    /* All outstanding allocations are
                                           returned to Exec */


     Here are the default allocmem() and freemem() callbacks that SHADOW
     uses to allocate and free memory from Exec.  These functions are
     called everytime a new chunk of 32items is needed from Exec.

          void * __regargs temporaryAlloc(struct MemoryList *list)
          {
             return AllocMem(32 * list->memlst_size +
                              sizeof(struct MemoryNode),
                             MEMF_PUBLIC);
          }

          void __regargs temporaryFree(struct MemoryList *list,
                                       struct MemoryNode *node)
          {
               FreeMem(node, 32 * list->memlst_size +
                             sizeof(struct MemoryNode));
          }


     Again, because SHADOW is principly designed for multi-threaded work,
     these memory lists use semaphores for each AllocateItem() and
     FreeItem() call.  If you don't need this protection, set the
     memlst_semUse to FALSE, and the EXEC Signal Semaphore that is a part
     of the MemoryList structure will not be used.  [You should set
     the semUse flag AFTER the InitTable() is called, and not before!]

     The relative performance of SHADOW is hard to measure because Exec's
     memory allocation and freeing routines can differ by a factor of
     five.  However, SHADOW's memory allocation routines, even
     WITH the semaphore, are about as fast as I've ever seen Exec's
     routines.  Without the semaphore they are obviously faster.

     What is plainly (painfully!) obvious is how bad Exec's routines
     degenerate when frees are perfectly interleaved (that is, when
     all of the odd numbered allocations are freed first, and then
     all the even numbered allocations are freed).  SHADOW is
     faster in this case by, at least, a factor of ten!

     Obviously, if the semaphore is not needed, SHADOW's memory routines
     are much faster than Exec's memory routines.  No attempt has been
     made to compare SHADOW's routines with anything other than Exec's
     AllocMem() and FreeMem() calls.  It is possible that some of Exec's
     other routines would be faster (in certain cases) than SHADOW's.
     It is up to the programmer to decide which set of functions best
     suits his or her purpose.



                                     OOPL

     Now that you know a little about the functional interface to the
     library, it is high time to introduce the object-oriented interface.
     However, this seems to be a good time to mention what SHADOW is NOT.
     SHADOW is not an Object-Oriented Programming Language (OOPL).  It is
     also not a Concurrent-Object-Oriented Programming Language.  Indeed,
     it is not a language at all.  It is entirely possible to envision a
     language built around SHADOW at some point in the future.  For right
     now, however, SHADOW is accessed via the 'C' language.

     So why not have built around an existing object-oriented language?
     True, the addition of semaphores, avl-trees, system strings, and
     even (with a bit of work) resource tracking, would all be possible
     under a language such as C++.  However, rewriting C++'s method
     dispatcher to provide for the synchronous and asynchronous method
     sends would have proved difficult, as C++ doesn't have one.

     Indeed, the languages that do exist which have concurrency syntax
     are usually built not only as "concurrent" languages, but as
     "distributed, concurrent" languages.  This type of abstraction
     is not necessary on the Amiga as the Amiga has only a single
     "process-space".  And yes, this implies you can't magically
     hook up two Amigas with SHADOW and expect things to work
     twice as fast together (or together at all at whatever speed).
     Remember, the design goal of SHADOW was to take advantage of
     the Amiga's better facilities -- principally among them, low
     overhead task switching and shared memory, not to add
     functionality.


                                Object Oriented

     So what is object-oriented programming anyway?  The classical
     definition of object-oriented programming is by example --
     ie: object-oriented programming was introduced to the world as a
     brand new way of programming, but the only formal definition
     offered was the example language implementations at the time
     (Smalltalk being the better known of these).  This is an unacceptable
     definition.  Unfortunately, the term has grown to mean a number
     of things to a number of people.

     However, there are some general "philosophies" behind Object-Oriented
     Programming.  Object-Oriented Programming attempts to model the
     world as a collection of "things" where these "things" have
     certain "characteristics" and are capable of performing certain
     "actions".  For instance, dogs are things that have certain hair-
     color, height, weight, etc.  Dogs can also do things like "bark",
     "eat", "sleep", etc.

     In addition to this, many object-oriented languages draw the
     distinction between definitive "things" and indefinite "things".
     For example, "-a- dog" is an example of an indefinite thing,
     whereas "-the- dog Rover" is an example of a definitive thing.
     As SHADOW makes this distinction this is not of purely
     academic interest.

     Object-Oriented Programming offers some names for the above, however
     while many of the names are consistent, some of them are not.  We
     will use the terminology that SHADOW uses.  if you wish to
     understand SHADOW against the wider diversity of object-oriented
     systems, you'll have to do some more reading.

     Under SHADOW, "things" are referred to as objects.  Often you will
     see the term in uppercase as in "OBJECTs" -- this is because
     "OBJECT" is an actual 'C' defined type (typedef), there is no
     difference here.  Some later distinction is drawn between "Object"
     and "object," but that is immaterial to this discussion.  Under
     SHADOW, indefinite things are objects, definite things are objects,
     everything is an object.

     An indefinite object is referred to as a class (or, alternatively in
     some of the docs, as a "cob_class").  A definite object is called
     an instance.  A definite object is always an instance of a particular
     corresponding indefinite object.  For example, "Rover" is an
     instance of "dog":


                      Real World   Object World   Description
                      ----------   ------------   -----------------
                         DOG    -- class       -- indefinite object
                         Rover  -- instance    -- definite object


     In addition, these object have physical "characteristics" and they
     possess the ability to perform "actions".  Under SHADOW, these
     charateristics are referred to as attributes, and the actions are
     referred to as methods.  In addition, attributes and methods are
     both -described- in a class, not in an instance.  For example,
     when we model a dog in the computer system, we define certain
     characteristics and actions that dogs, in general, will have
     and perform.  A dog has a certain hair color, weight, height,
     and they all know how to bark, eat, and sleep.  Rover, as an
     instance of this imaginary dog-class, automatically would contain
     the space for its characteristics, and could call the "bark",
     "eat", and "sleep" routines that were specified in the class.

     We can imagine some simple code that illustrates this:

          new CLASS called DOG {
               Attributes:
                  weight is a float
                  height is a float
                  hair-color is a set containing (black, brown, white)

               Methods:
                  bark:
                     play_sound "dh0:samples/barkingDog"
                     end
                  eat:
                     say "Munch, munch, slurp, slurp, munch, munch."
                     end
                  sleep:
                     display "dh0:pictures/SleepingDog.pic"
                     end
          }

          new INSTANCE called ROVER of CLASS DOG {
               weight = 13.2
               height = 33.6
               hair-color is (brown, black)
          }

     At this point you can do something like:
          ROVER bark

     and ROVER would 'play_sound "dh0:samples/barkingDog"'.

     Obviously, while the syntax is different, there hasn't been much
     gained over straight 'C' here.  But we aren't quite finished yet!

     There is yet one more feature to Object-Oriented Programming, and
     that is the notion of "subclassing".  Subclassing is the heart
     of "reuse' -- the notion that old code never dies, it just gets
     recycled.  Let's take the same dog example again.  Dogs are nice,
     for some people, but others prefer a particular -subclass- of
     dogs, say, hunting dogs.  A hunting dogs do useful things like
     retrieving dead ducks from slimey swamp pits.  So, we have the
     following pseudocode:

          new CLASS called HUNTING_DOG as SUBCLASS of DOG {
               methods:
                  retrieve:
                     exists duck?
                        print "Dog now has duck"
                     else
                        object bark
                     end
          }

          new INSTANCE called SPOT of class HUNTING_DOG {
               weight = 15.2
               height = 30,5
               hair-color is (black, white)
          }

     Notice that the HUNTING_DOG instance SPOT can specify all the
     attributes that ROVER did.  This is because HUNTING_DOG "inherits"
     the attribute definitions from its "superclass", DOG.

     In addition, if there was no duck, and you did the following:

          SPOT retrieve

     SPOT would bark (else...  object bark)!  Just as HUNTING_DOG
     inherits attributes, it inherits the methods of DOG as well.

     There is one more possibility:

          ROVER retrieve

     Remember, ROVER is not a HUNTING_DOG.  ROVER, therefore, does not
     know how to retrieve   Under SHADOW, nothing happens (an error
     code is set in your process object, though).  In C++ this causes
     a compile-time error, and in Objective-C it causes a program
     failure ("Unimplemented Method").  SHADOW is a bit more forgiving
     than either of these languages....


                  Object-Orientedness under SHADOW

     That taken care of, you can imagine that creating class descriptions,
     in particular the descriptions of attributes and methods of a new
     class, in 'C' can be quite challenging.  And I'm afraid that you
     would be correct in that assessment.

     The rest of this document focuses on the issue of creating new
     classes and describes the inter-relationships of the classes
     provided to you by SHADOW.

     The document 'ShadowLibraryMethods.doc' introduces SHADOW's
     object-oriented system.  Excepting some brief reiterations
     and clarifications, that document will continue to contain
     the main introduction to the object-oriented system.  Therefore,
     it is not merely highly suggested that you read the introduction
     in ShadowLibraryMethods.doc, it is prerequisite that you do so.

     To reiterate, aside from the functional aspects of SHADOW which
     are introduced above, everything under SHADOW is an object.  All
     SHADOW objects begin with a struct CoreObject which can be found in
     <shadow/core.h>.  There are two fields in this structure, the
     cob_useCount and the cob_class.  The cob_useCount is used by the
     resource tracking system and is covered earlier in this document.
     The cob_class points to another OBJECT which contains the
     information that is necessary to create, destroy, and otherwise
     maintain this object.  In short, this description (or blueprint or
     class), contains a description of the attributes (or properties) of
     the object and the methods (or functions, or verbs) of the object.

     The relationship between "object" and "cob_class" is called the
     "instantiation hierarchy".  Object-oriented systems typically
     describe classes in relation to other classes.  The former group
     of classes are called subclasses, and the latter are called
     superclasses.

     In the case of the "superclass hierarchy", there is a class which
     has no superclass.  This class is typically referred to as the
     rootclass.  In the case of SHADOW's "instantiation hierarchy", there
     is no object without a cob_class, after all, an object without
     a description is pretty hard to create!  However, there is a
     descriptor which, instead of terminating the instantiation
     hierarchy, is a descriptor for itself.  These descriptions
     are referred to as METAs.

     The instantiation hierarchy for SHADOW is three deep.  For a summary,
     please refer to the "instantiate hierarchy" entry in the Glossary.doc.

     This three-level setup allows you, the programmer, to change
     the methods of both your objects (by changing the method
     descriptions in your classes) -and- your classes (by
     changing the method descriptions in your metas).

     There is more about METAs in ShadowLibraryMethods.doc, and I suggest
     you read about them there as well.  This document is more concerned
     with how you actually create classes and metas, rather than what
     classes and metas -are-.


                              Creating Classes

     Classes contain two important descriptions -- attribute descriptions
     and method descriptions.  Attribute descriptions are very
     straightforward.  Method descriptions can become very complicated.

     Classes are created by specifying the new class name, the superclass,
     the new methods, and the new attributes like so:

         CreateSubClass(NULL, ROOT_CLASS, META_CLASS,
                                          MY_CLASS_NAME,
                                          NULL,
                                          myNewAttrs,
                                          myNewMethods,
                                          METHOD_END);

     AttributeTags

     The attribute description is a NULL-terminated array of ATTRIBUTE_TAGs.
     Each element contains the following information:
          typedef struct AttributeTag {
             char          *attag_name;
             ULONG          attag_size;
             void          *attag_default;
          } ATTRIBUTE_TAG;

     The attag_name is the name of the attribute.  When you have an instance
     of your created class you can access this attribute inside of the
     instance by calling the FindAttribute() function passing in the
     attag_name of the attribute you want access to.

     The attag_size is the size of the particular attribute you want
     created.

     The attag_default is a pointer to a structure containing the
     default values of the attribute.  If this is not specified, the
     default value for the entire attribute-structure will be zeroes.

     Consider the following example.  Say you wanted to create an object
     that described a car.  You want to keep certain information
     about this car inside of an attribute.

     First thing is to create a C structure:
          struct CarInfo {
               ULONG     ci_wheelSize;
               ULONG     ci_steeringSide;
               .
               .
               .
          };
     In this example, the ci_wheelSize refers to the size of the wheels
     on the car and the ci_steeringSide refers to the side of the
     car that the steering wheel is on, and so forth.

     The next thing to do is to pick a name for the attribute.  Please
     note that the name is case-sensitive!:

          #define ATTR_MY_CAR_INFO "My information about this car"

     We can now create the ATTRIBUTE_TAG structure:

          ATTRIBUTE_TAG myNewAttrs[] = {
               {
                    ATTR_MY_CAR_INFO,
                    sizeof(struct CarInfo),
                    NULL
               },
               TAG_END
          };

     If we had wanted to we could have created default values for the
     attributes so that when the class' instances are created, they
     automatically have some non-zero values in them:

          struct CarInfo defaultCarInfo = {14, LEFT, ...};

     In which case the ATTRIBUTE_TAG structure becomes:

          ATTRIBUTE_TAG myNewAttrs[] = {
               {
                    ATTR_MY_CAR_INFO,
                    sizeof(struct CarInfo),
                    &defaultCarInfo
               },
               TAG_END
          };


     The creation of the class would necessarily follow this.  Note that
     this code makes the class a resource that will be freed when the
     process defining the resource exits:

          AddAutoResource(NULL, CreateSubClass(NULL,
                                               ROOT_CLASS,
                                               META_CLASS,
                                               CAR_CLASS,
                                               NULL,
                                               myNewAttrs,
                                               METHOD_END),
                                CAR_CLASS);

     Once we had this class, we can create an instance of the class:

          automobile = CreateInstance(NULL, CAR_CLASS, META_CLASS);

     So, now that an actual car instance exists, you can access the car's
     instance variables (the attributes of the instance), with the
     following code:

          {
             struct CarInfo *ci;

             ci = FindAttribute(automobile, ATTR_MY_CAR_INFO);

             .
             .
             .

          }

     Once you have a pointer to the object's instance variables, you can
     manipulate the structure, change variables, etc.  However, this
     pointer will only remain valid as long as the object it is assoicated
     with remains valid.  In other words, once you
     "DropObject(automobile)", you may not use the "ci" variable again.
     After all, the object may have been destroyed!

     In addition, if this structure is to be shared across many processes,
     you will want to protect access via the semaphore system (described
     above).  Fo all of my code I use the "ci" pointer to semaphore the
     entire structure.  You may find a more suitable way of doing the
     same thing, if you wish.  At anyrate, your code might look like:

          {
             struct CarInfo *ci;

             ci = FindAttribute(automobile, ATTR_MY_CAR_INFO);
             PSem(ci, SSEM_READ);

             .
             . // Various reads on the structure taking place.
             .

             VSem(ci);
          }



     The next step involves showing off a shortcut in SHADOW.  SHADOW's
     attributes, as defined by both META_CLASS and META_CLUSTER, are
     created in the order that they are specified.  This means that if
     you create two attributes, one after the other, a pointer to
     the first structure will easily lead you to a pointer to the second.


          struct CarInfoExternal {
               ULONG     cie_wheelSize;
               ULONG     cie_wheelBase;
               .
               .
               .
          };
          #define ATTR_CAR_INFO_EXT "Information about the car's externals"

          struct CarInfoInternal {
               ULONG     cii_headClearance;
               ULONG     cii_cubicCapacity;
          .
          .
          .
          };
          #define ATTR_CAR_INFO_INT "Information about the car's internals"

          ATTRIBUTE_TAG myNewAttrs[] = {
               {
                    ATTR_CAR_INFO_EXT,
                    sizeof(struct CarInfoExternal),
                    NULL
               },
               {
                    ATTR_CAR_INFO_INT,
                    sizeof(struct CarInfoInternal,
                    NULL
               },
               TAG_END
          };

          .
          .
          .

          AddAutoResource(NULL, CreateSubClass(NULL,
                                               ROOT_CLASS,
                                               META_CLASS,
                                               CAR_CLASS,
                                               NULL,
                                               myNewAttrs,
                                               METHOD_END),
                                CAR_CLASS);

          automobile = CreateInstance(NULL, CAR_CLASS, META_CLASS);

     Assuming the above, the following:

          {
             struct CarInfoExt *ce;

             ce = FindAttribute(automobile, ATTR_MY_CAR_INFO);

             .
             .
             .

          }

     is identical to this:
          {
             struct CarInfo *ci;

             ci = FindAttribute(automobile, ATTR_MY_CAR_INFO);

             .
             .
             .

          }

     where "struct CarInfo" is declared as follows:
          struct CarInfo {
               struct CorInfoExt   ci_cie;
               struct CarInfoInt   ci_cii;
          }

     As is apparent from this, a pointer to the first structure may very
     well be useful to getting at other data.  The advantages of having
     separate attributes in the first place is to save space when using
     explicitly declared default attributes, or if you wish to offer
     the ability for subclasses to alter the default values for some
     subset of your attributes without affecting some other subsets
     of your attributes.


     The above is an example of a time optimization.  Instead of looking
     up both attributes separately, only one was looked up, and the
     second attribute's address was able to be hard-coded.

     A similar improvement is possible when looking up attributes
     frequently within methods.  You can lock a global pointer to a class
     and then lookup the "struct Attribute" which contains the necessary
     information to later find the attribute locations within any instance
     of that class.  Note that you will have to keep that global
     pointer "locked" in memory for the entire time that the Attribute
     structure is being used.

          DropObject(SetObject(&globalClass, FindShadowClass(CAR_CLASS)));
          /*
           * Note that FindShadowClass() returns a used class here.
           *
           * We use SetObject() to avoid race-conditions if
           * more than one task tries to set the variable at
           * the same time.
           */

          struct Attribute *globalAttr = FindAttrDefn(globalClass,
                                                      ATTR_INFO);

          /*
           *
           * We should not DropObject(globalClass) until we no longer
           * need the attribute.
           */
          .
          .
          .

          Now, say you have some instance 'object', and it is the correct
     class (object->cob_class = globalClass or somes subclass of
     globalClass).  Now you may merely add the value in the attr_offset
     field within the attribute structure to the instance address and
     arrive at the attribute within the object:

          .
          .
          .
          {
               struct Info *info = (void *)(((ULONG)object) +
                                            attr->attr_offset);
               .
               .
               .
          }
          .
          .
          .


     This will occur far faster than the FindAttribute() call.  The two
     disadvantages are the initial startup costs and shutdown costs, as
     well as the necessity to keep the class "locked" in memory for the
     entire time you have a globalAttr pointer.

          .
          .
          .
          /*
           * CLEANUP!
           *
           * As we no longer need the globalAttr, we clear the globalClass
           */
          DropObject(SetObject(&globalObject, NULL));


     The only remaining thing to note about attributes is this: once the
     class is created, the AttributeTag structures -and- the default
     attribute structures are no longer needed by the system.  The
     system copies everything into memory when the class is created, so it
     is very possible to have the AttributeTags and the default values
     reside in a text file and load the text file at runtime, and then
     purge the text file.

     This means that changing the default attribute structure after the
     class is created will NOT change the creation of future objects.
     You can change these default attributes pretty easily, however.  Here
     is some example code.  It takes a longword value within the default
     object and updates it according to a hex value:

          {
             ULONG *ptr = GetDefaultAttribute(myClass, ATTR_WEBPAUSE, 0);

             /*
              * ptr may or may not exist!  If ptr did not exist, then
              * the attribute did not originally have a default
              * attribute and the machine ran out of memory trying to
              * allocate one, or the attribute itself did not
              * exist within the passed class.
              */
             if (ptr)
                /*
                 * Convert the hex-string in args[0] and save the number
                 * into the longword pointer.
                 */
                stch_l(args[0], ptr);
          }

     GetDefaultAttribute() is defined as follows:

          /*
           * Looks for a default attribute object for the name'd
           * definition.
           *
           * Returns either NULL (failure) or the default object + offset.
           *
           * Will create a default object if it doesn't exist.
           * Will create a NEW default object if the superclass has the
           *  same default object.  Note, subclasses -share- the same
           *  default attribute object with their superclasses
           *  [or, rather, vice-versa].
           *
           * Watched attributes do not -have- default values.
           */
          void *GetDefaultAttribute(CLASS class, char *name, ULONG offset)
          {
             struct Attribute *attr = FindAttrDefn(class, name);
             struct Attribute *temp;
             struct ClasslessObject *obj;

             if (!attr || (attr->attr_size & FLAG_ATTR_WATCHED))
                return NULL;

             temp = FindAttrDefn(class->ccl_superClass, name);
             if (!(obj = attr->attr_value) ||
                 (temp && obj == temp->attr_value))
             {
                if (obj)
                {
                   /*
                    * Create a new object for the subclass and copy
                    * in the values from the superclass' default
                    * object.
                    */
                   if (!(obj = CreateObject(obj + 1, attr->attr_size)))
                      return NULL;
                } else
                {
                   /*
                    * If we have no default object, then the default
                    * values are all zero.
                    */
                   if (!(obj = AllocMem(sizeof(struct ClasslessObject) +
                                           attr->attr_size,
                                        MEMF_PUBLIC | MEMF_CLEAR)))
                   {
                      return NULL;
                   }
                   /*
                    * Setup the new object with a size and usecount
                    */
                   obj->clb_size = sizeof(struct ClasslessObject) +
                                        attr->attr_size;
                   obj->clb_useCount = 1;

                }
                /*
                 * Save the new default object into the class --
                 *  drop any old default objects there, and make sure
                 *  the operation is single-threaded.
                 */
                DropObject(SetObject(&attr->attr_value, obj));
             }

             /*
              * Returns a pointer into the default object so that you
              * cn directly dork with the values.
              */
             return (void *)(((ULONG)(obj + 1)) + offset);
          }


     MethodTags

     As mentioned above, attribute creation is fairly straightforward --
     when compared to method creation.  And that's because creating a
     method involves a lot more than just creating a couple of structures.
     It involves considering the types of methods you have available --
     synchronous, asynchronous, call-by-port, call-by-process.  It also
     involves creating the actual functions and function argument tags,
     and the process classes (and instances) that you might need to run the
     method inside of.

     This presents the creation of several types of methods from the
     function-level up.  However, you should realize that the process is
     not always so straightforward.

     A method's function always has at least the following four arguments:
          struct IPCMessage *msg;
          OBJECT            object;
          META              class;
          char              *MethodID;

     The <msg> parameter is used by the asynchronous method sends.  It
     is provided for handling some strange resource-tracking cases that
     are discussed below.  This parameter is often NULL.

     The <object> parameter is the object on which the selector is being
     invoked.  This parameter is never NULL.

     The <class> parameter is a pointer to the class of the object that
     actually handles the given MethodID.  Remember, every object is an
     instance of some class.  Classes live in a class-hierarchy from which
     they inherit other class' methods.  Therefore, when a particular
     method is invoked, the method itself might be handled by the object's
     class, or some superclass of the object's class.  This parameter
     distinguishes -which- class handles the passed selector....

     The <MethodID> parameter is a pointer to a system-string which
     corresponds to the selector for this particular method.  It is a
     useful way to allow multiply different methods to converge on one
     of your functions, and then diverge when the method is sent off
     to the superclass for further handling.

     Obviously, typing all of this information into each function would
     be tedious.  The includes defines the macro "METHOD_ARGS", which
     contains these argument definitions.  The ability of your compiler to
     handle this shortcut may differ from mine....

     Here is a sample method-function definition:

          void ProcTestMethod(METHOD_ARGS)
          {
             BPTR oldoutput;

             oldoutput = SelectOutput(Open("CONSOLE:", MODE_OLDFILE));

             VPrintf("Called method: <%s> ", (ULONG *)&MethodID);
             VPrintf("in process <%s>\n", (ULONG *)&FindTask(NULL)->
                                                    tc_Node.ln_Name);
             VPrintf("\tin Class <%s> ", (ULONG *)&(CurrentProcess()->
                                                    cob_class->meta_name));
             VPrintf(((msg)?"Asynchronously\n":"Synchronously\n"), NULL);

             oldoutput = SelectOutput(oldoutput);
             Close(oldoutput);

             CallSuper();
          }

     This is a relatively simple method-function that the included perftest
     program uses to verify nearly all of the method-invoke possiblities
     (by function, synchronous msg, asynchronous msg, etc).


     Once you have this function written, you need to create an
     ARGUMENT_TAG structure which describes the addition arguments that
     the method tags (above the four described above).  Because this
     method does not take any extra arguments, we will postpone talking
     about ARGUMENT_TAGs until we have a more appropriate example.

     Now we have to create a name for the selector of this method:

          #define METH_MY_NEW_PROC_TESTER "A string of your own choosing"

     The next thing to do is to add the method into your class' METHOD_TAG
     list.  The METHOD_TAG list has eight different variables.  We take
     each in turn.

     The first field in the METHOD_TAG structure is the mtag_MethodID
     field.  This field is very straightforward -- it should always
     carry a non-NULL field that is a pointer to the string which is
     to represent the method's selector.

     The next two fields are named: mtag_procObject and mtag_defnObject.
     Although they have similar names, their meanings are very different.
     The mtag_defnObject is used by the system to ensure that the program
     (or some other loaded code, like a library) which contains the
     definition of the function and the ARGUMENT_TAG in its seglist,
     does NOT disappear until all reference to the function by any
     methods in any classes are eliminated.


     mtag_defnObject:

     Here's the basic problem.  Program A has loaded a method, M.  Program
     A now defines a public class C which has the method M.
     Program B now comes along, creates an instance I of class C.  Program
     A quits.  Program B tries to invoke method M of instance I, which used
     to reside in Program A, but has been since eliminated.  This is
     clearly not good.  The same thing might happen for a library base
     (although the OpenCnt of the library base should be enough to
     catch all legal errors in this respect).

     What we do in the instance of a library is to define a global,
     classless object, and use the pointer to this global object as the
     defn_object:
                    struct ClasslessObject
                              globalLibraryObject = {0, 0, 0};

     In the EXPUNGE code, you'll want to verify that the
     globalLibraryObject.cob_useCount is zero.  If it is a non-zero
     integer, then someone still has a pointer to an object that has
     a class (or some superclass thereof) that points to a method in
     your library.  Thus, your method may still be called, and you
     should refuse to expunge your library.

     This is a distinct advantage over BOOPSI where class libraries are
     difficult to manage because of the various resource tracking issues.


     However, creating methods inside of libraries is not likely to be
     the most frequent thing you do.  Far more frequently you will be
     creating classes inside of programs.  And for this, you will need to
     retrieve the CurrentProcess() -- a pointer to your process' object
     that was created during the InitOOProgram() call (the FIRST function
     you should always call after your OpenLibrary("shadow.library", 5) is
     InitOOProgram()!!! -- see the Process Class discussion below).

          /*
           * CurrentProcess() is a macro defined in <shadow/shadowProto.h>
           *
           * This object is not resource tracked, so you need not
           *  DropObject() this processObject after you're done using it.
           */
          processObject = CurrentProcess();

     Once you have this pointer, you modify each of your MethodTags to
     have the mtag_defnObject point to the CurrentProcess() object.
     This is tedious, and the funcion SetupMethodTags() is provided to
     help you in this respect.  We will talk more about SetupMethodTags
     when we begin the discussion of mtag_procObject.

     It stands to reason, as well, that you need to be in the process
     that the program runs in!  In otherwords, FindTask(NULL) had
     better be your program's task, or you are going to end up with the
     wrong process!

     At anyrate, once your class is created, your program cannot exit
     before the methods are no longer callable via this class because the
     last call your program should make before the CloseLibrary(ShadowBase)
     is the RemoveCurrentProgram() call, which will not return until all
     references to your CurrentProcess() go away.  Again, you have a safe
     way in which to define public classes and ensure no one has a pointer
     to your internal methods when your program ends up quitting and
     returning its resources to the system.


     mtag_procObject:

     The mtag_procObject is used to help determine what process the
     object's method needs to be run in.  SHADOW is very flexible in its
     ability to run methods in other processes.  You can ask for something
     as simple as a function call, or something much more complicated,
     like "invoke a method by creating a process of the given named class;
     then, replace the named class with a pointer to the actual class
     pointer so that the next invocation no longer has to look the class
     up in the class list."

     While the mtag_defnObject is always a SHADOW object, the
     mtag_procObject can be any number of things.  Some of the mtag_flags
     are used to decide what the mtag_procObject is pointing to.

     A valid mtag_procObject is one of five values:
          a) it is a pointer to a process object.
          b) it is a pointer to an IPCPort.
          c) it is a pointer to a process class
          d) it is a pointer to a struct MethInvokeSpec <shadow/method.h>
          e) it is NULL


     mtag_flags:

     There are five flags in the mtag_flags which control the behaviour of
     these various possibilities:

          METH_FLAG_OBJECT  - The mtag_procObject is interpreted as the
                               destination process object.
          METH_FLAG_PORT    - The mtag_procObject is interpreted as an
                               IPCPort to which method-messages are sent.
          METH_FLAG_CLASS   - The mtag_procObject is interprted as a
                               class of process objects.  This class is
                               instantiated, and the resulting process
                               object is used as the destination for
                               that particular method invocation.

          METH_FLAG_OBJECT_AS_DEST
                            - The object the method is being invoked on is
                               itself used as the destination process
                               object.  This is particularly useful for
                               process methods which must (for reasons of
                               port allocation or other signal-bit
                               allocation, etc.) be run in the process
                               with which the process-object corresponds.

          METH_FLAG_SPEC    - The mtag_procObject is interpreted as a
                               pointer to a struct MethInvokeSpec
                               [see: <shadow/method.h>], the complete
                               meaning of which depends on the above four
                               flags in the following manner:

             METH_FLAG_SPEC | METH_FLAG_OBJECT
                mis_instanceName is the name of the process object to use
                                  as the destination object.
                mis_className    is the class name of the class of the
                                  above process object.
                mis_metaName     is the meta's name of the meta of the
                                  above class.  Usually this is
                                  META_CLASS.

             METH_FLAG_SPEC | METH_FLAG_PORT
                mis_instanceName is the name of the IPCPort to use as the
                                  destination port.  This port will NOT
                                  be created, but must exist when the
                                  method is called.
                mis_className    is NULL
                mis_metaName     is NULL

             METH_FLAG_SPEC | METH_FLAG_CLASS
                mis_instanceName is NULL
                mis_className    is the class name of the process to
                                  create.
                mis_metName      is the meta's name of the meta of the
                                  above class.  Usually this is META_CLASS.

             METH_FLAG_SPEC | METH_FLAG_OBJECT_AS_DEST
                the METH_FLAG_SPEC is meaningless in this case as the
                METH_FLAG_OBJECT_AS_DEST never uses the mtag_procObject
                field.


                               When the process/port is looked-up/created,
                               the process/port may replace the
                               MethInvokeSpec structure, eliminating the
                               need to lookup the object/class/port again.
                               To do this, set the SPEC_SAVE_BINDING flag
                               in the mis_flags field of the MethInvokeSpec
                               structure.


     A NULL mtag_procObject is treated differently depending on the
     mtag_flags and the mtag_threadstat.  As the mtag_threadstat hasn't
     been discussed yet, though, it makes sense to do that first.


     mtag_threadstat:

     Where the mtag_flags field describes how the mtag_procObject is
     interpreted during a method call, the mtag_threadstat determines how
     the method is actually invoked.  The following flags are defined in
     <shadow/message.h>:

         INVOKE_CALL       - Calls method as function.

         INVOKE_SYNC       - The method is invoked as a synchronous message
                              to the method's mtag_procObject, unless the
                              calling process belongs to a subclass
                              of the destination's process' class,
                              in which case the method is called as a
                              function.

         INVOKE_ASYNC      - The method is invoked as an asynchronous
                              message to the method's mtag_procObject,
                              unless the calling process belongs to a
                              subclass of the destination's process'
                              class, in which case the method is called
                              as a function.

         INVOKE_FORCE      - Used in onjunction with above two flags.  See
                              next two flags.

         INVOKE_FORCE_SYNC - The method is sent as a synchronous message
                              unless the calling process is exactly
                              equivalent to the destination process, in
                              which case the method is called as a funcion.

         INVOKE_FORCE_ASYNC- The method is ALWAYS sent as an asynchronous
                              message.  Irregardless of calling/destination
                              process.

         INVOKE_IGNORE_PROCESS
                           - It is possible for programers to call DSM()
                              and its associated helper functions
                              (eg. DoShadowInProcess()) to override the
                              process that the method is handled in.
                              Setting this flag in the mtag_threadstat
                              prevents the mtag_procObject from being
                              overridden with the INVOKE_WITH_PROCESS
                              flag that can be sent to DSM().  See the
                              Autodoc for DSM() for more information.


     As you can see, there are a variety of ways in which to call a method.
     You can call a method asynchronously to a named IPCPort (mtag_flags
     would be METH_FLAG_PORT | METH_FLAG_SPEC, mtag_threadstat would be
     INVOKE_FORCE_ASYNC, and mtag_procObject would be a pointer to a
     MethInvokeSpec structure) or invoke a method as a simple function
     call (mtag_flags would be METH_FLAG_OBJECT, mtag_threadstat would be
     INVOKE_CALL, mtag_procObject would be NULL).  Many of the callable
     attributes are overridable at method invoke-time, so you can
     determine how the method is invoked both in the method definition
     (which is being discssed here) and method invocation (which will be
     described briefly here, and is described more fully in the DSM()
     autodoc).

     When mtag_procObject is NULL, there are several possible reactions by
     SHADOW, depending (as mentioned above) on the mtag_flags and
     mtag_threadstat settings:

          INVOKE_CALL         - NULL mtag_procObject is ignored, call
                                 proceeds as usual.

       mtag_flags = METH_FLAG_OBJECT:

          INVOKE_[FORCE]_SYNC - Method is only successfully called if the
                                 calling task has no associated SHADOW
                                 object.  Otherwise DSM() or its helper
                                 functions (eg. DoShadow()) returns NULL.
                                 If the calling task has no associated
                                 SHADOW object, the method is invoked as
                                 a function call.

          INVOKE_[FORCE]_ASYNC- Similar logic to the INVOKE_SYNC logic
                                 above except that INVOKE_FORCE_ASYNC where
                                 the mtag_procObject is NULL will force an
                                 asynchronous method-invoke message to be
                                 sent to the calling task's SHADOW-method
                                 port, stored in the sp_port field of the
                                 struct ShadowProcess structure in the
                                 ATTR_SHADOWPROCESS attribute of the
                                 process' object.  If there is no current
                                 task, the message should be called as a
                                 function.


       mtag_flags = METH_FLAG_PORT
               -or-
       mtag_flags = METH_FLAG_CLASS

          A NULL port/class (mtag_procObject), except when mtag_threadstat
          is INVOKE_CALL, will cause the method invocation to fail.  DSM(),
          or its helpers (eg. DoShadow()), will return NULL.


       mtag_flags = METH_FLAG_OBJECT_AS_DEST

          A NULL mtag_procObject is meaningless as the object argument of
          the DoShadow() call (or the first pointer in the arguments
          array to DSM()) is used as the process object to which to send
          the method.


       mtag_flags | METH_FLAG_SPEC

          Not specifying a pointer to a MethInvokeSpec structure in the
          mtag_procObject when the flag METH_FLAG_SPEC is set in the
          mtag_flags field is a programming error.  Your class will not
          be created under these conditions.  mtag_procObject MUST be
          non-NULL, and had BETTER point to a MethInvokeSpec structure.
          This MethInvokeSpec structure is copied when the class is
          created, so you need not have your MethInvokeSpec structures
          lying around after your classes are created.

     mtag_priority
          This field is only used by the PATCHER_CLASS.  It is ignored
          by the class, though you set it to zero for future
          compatibility.

     mtag_method
          This should contain a pointer to the function which implements
          the method.

     mtag_arguments
          This should point to an ARGUMENT_TAG array that describes the
          arguments the method's function takes (this allows asynchronous
          methods to have their arguments correctly resource-tracked),
          and describes the return value of the function.  If the function
          does not return anything, and there are no arguments above and
          beyond the METHOD_ARGS default arguments of all methods, then
          this field may be NULL.  The pointer to this supplied
          ARGUMENT_TAG is -not- copied, although the contents of the
          ARGUMENT_TAG MUST remain constant.  The ARGUMENT_TAG should
          be considered a part of the method's function, rather than as
          an extension to the data that describes the method (METHOD_TAG).
          That data (the METHOD_TAG) is copied and altered appropriately
          when the class is created.


     Given this information, here is an example METHOD_TAG which enables
     the associated class to invoke the METH_MY_NEW_PROC_TESTER method
     and have this translated into a function call to the ProcTestMethod()
     function which was described several pages ago:

          METHOD_TAG myNewMethods[] = {
                                        .
                                        .
                                        .
                                        <other methods for this class>
                                        .
                                        .
                                        .
                                        {
                                           METH_MY_NEW_PROC_TESTER,
                                           NULL, NULL,
                                           INVOKE_CALL,
                                           METH_FLAG_OBJECT, 0,
                                           (METHODFUNCTYPE)ProcTestMethod,
                                           NULL
                                        },
                                        TAG_END
                                      };

     Notice that this method tag does not specify an mtag_procObject nor
     an mtag_defnObject.  For this particular METHOD_TAG item, the
     mtag_defnObject needs to be set to the CurrentProcess() and the
     mtag_procObject can remain NULL.  However, it is quite possible that
     other METHOD_TAG items need to have their mtag_procObject be
     something other than NULL, and it is perfectly fine to specify
     an mtag_procObject as any process object you wish when the
     mtag_threadstat is INVOKE_CALL and the METH_FLAG_OBJECT is set.

     As the CurrentProcess() is only available at runtime, you can either
     iterate through the METHOD_TAG array and setup the defnObject and
     the procObject as you wish, or you can use the supplied
     SetupMethodTags() routine.

     SetupMethodTags takes three arguments -- the METHOD_TAG array, the
     procObject to be used in each element of the array, and the defnObject
     to be used in each element of the array.  If either of these last two
     arguments are specified as "-1", then the results of CurrentProcess()
     are used.  If the item already has a defnObject or procObject
     specified (non-NULL), then that field remains untouched.  This is
     especially useful when using the MethInvokeSpec structure as the
     mtag_procObject -- this is a static structure which can be set at
     compile-time....

     Please note!  When setting the elements of this array, SetupMethodTags
     does not UseObject() any of the objects.  Therefore, be careful if
     you ever define a new type of MetaClass which allows for classes to
     be defined asynchronously to the caller, as the mtag_procObjects and
     the mtag_defObjects will not be correctly resource-tracked....  This
     is not a problem for the default CreateSubClass() call which 99% of
     you will be using.

     The corresponding SetupMethodTags() for this METHOD_TAG structure
     looks as follows:

          /*
           * Set all procObjects and defnObjects to CurrentProcess();
           */
          SetupMethodTags(myNewMethods, (void *)-1, (void *)-1);

     The creation of the class would then follow this.  Note that this
     code makes the class a resource that will be freed when the
     process defining the resource exits -- also, we use the "myNewAttrs"
     ATTRIBUTE_TAG which is defined several pages back:

          AddAutoResource(NULL, CreateSubClass(NULL,
                                               PROCESS_CLASS,
                                               META_CLASS,
                                               MY_PROC_CLASS,
                                               NULL,
                                               myNewAttrs,
                                               myNewMethods,
                                               METHOD_END),
                                MY_PROC_CLASS);


     We now possess a new MY_PROC_CLASS with some attributes and some methods.
     Of course, to call a method, we first need an instance!

          process = CreateInstance(NULL, MY_CAR_CLASS, META_CLASS);

     And now to call the new method:

          DoShadow(process, NULL, METH_MY_NEW_PROC_TESTER, METHOD_END);

          .
          .
          .
          /*
           * Don't forget your cleanup!
           */
          RemoveObject(process);


     The DoShadow() call is very straightforward -- first the object, then
     the class at which to begin looking for the method (NULL signifies
     object->cob_class, which is the way you'll call 80-90% of all your
     methods), then the selector string, then any arguments that are
     expected by the method, and then a METHOD_END terminator.

     A few things need to be pointed out here.  First, you need not
     specify all your arguments before the METHOD_END.  Arguments
     which are not specified are set to zero by the method calling code.
     This allows you to create new versions of your software, adding new
     arguments to old methods, without having to worry about anybody
     else's additions to your classes!  Provided, of course, that NULLs
     default to the old version's behaviour....

     Second, not specifying the METHOD_END terminator is a bug in your
     code -- don't do it, even if it does work....

     Third, it is VERY IMPORTANT that no argument that you pass into the
     method has the same value as METHOD_END -- 0x80000001 -- or,
     alternatively, that no two adjacent WORD arguments, combined, form a
     0x80000001.  This value was picked so as to be a very high negative
     number, an odd number (impossible address), and just plain unlikely
     to cause problems.  You will have to become clever if this is not the
     case for you....  Someday, a language might hide this detail from you,
     but you'll have to live with it for now.  If this is just not
     satisfactory, then let me suggest an alternative.  For all those
     items that require resource tracking -- strings, objects, structure
     pointers, pass those as separate arguments, and for all flags and
     numbers, etc., pass those arguments in a single method-argument as a
     TagArray structure pointer.  There is a 'TAGL' type of argument that
     will allow you to do just such a thing....

     Fourth, the CreateSubClass() and the CreateInstance() both have a
     METHOD_END terminator, and it now becomes clearer why -- they
     both cleverly use the passed stack arguments as arguments into a
     method call which creates either an instance of a class or a
     class itself....


     There is no reason why more than one method can call the same
     function.  The following is perfectly reasonable:

          #define METH_MY_NEW_PROC_TESTER_1 \
                                   "A string of your own choosing 1"
          #define METH_MY_NEW_PROC_TESTER_2 \
                                   "A string of your own choosing 2"
          METHOD_TAG myNewMethods[] = {
                                        {
                                           METH_MY_NEW_PROC_TESTER_1,
                                           NULL, NULL,
                                           INVOKE_FORCE_ASYNC,
                                           METH_FLAG_OBJECT, 0,
                                           (METHODFUNCTYPE)ProcTestMethod,
                                           NULL
                                        },
                                        {
                                           METH_MY_NEW_PROC_TESTER_2,
                                           NULL, NULL,
                                           INVOKE_SYNC,
                                           METH_FLAG_PORT, 0,
                                           (METHODFUNCTYPE)ProcTestMethod,
                                           NULL
                                        },
                                        TAG_END
                                      };

          .
          .
          .

          extern struct IPCPort *somePortSomeplace;

          /*
           * Set all procObjects and defnObjects to CurrentProcess();
           */
          SetupMethodTags(myNewMethods, (void *)-1, (void *)-1);
          /*
           * oops, but reset the port.
           *
           * We could have the line below and the line above switch
           * places as well!
           */
          myNewMethods[1].mtag_procObject = somePortSomeplace;

          /*
           * Create the class.
           */
          AddAutoResource(NULL, CreateSubClass(NULL,
                                               PROCESS_CLASS,
                                               META_CLASS,
                                               MY_PROC_CLASS,
                                               NULL,
                                               myNewAttrs,
                                               myNewMethods,
                                               METHOD_END),
                                MY_PROC_CLASS);

          AddAutoResource(NULL, process = UseObject(
                                   CreateInstance(NULL,
                                                  MY_CAR_CLASS,
                                                  META_CLASS)),
                          NULL);


          /*
           * Send off some methods....
           *
           * The first is called asynchronously.
           * The second is called synchronously and is handled by the
           *  "somePortSomeplace" IPCPort.  The same function
           *  (ProcTestMethod()) should be called regardless of
           *  this, however.
           */
          DoShadow(process, NULL, METH_MY_NEW_PROC_TESTER_1, METHOD_END);
          DoShadow(process, NULL, METH_MY_NEW_PROC_TESTER_2, METHOD_END);

          .
          .
          .
          /*
           * Hey, don't forget the cleanup!
           */
          DropObject(process);     /*
                                    * Matches my UseObject()
                                    *  above
                                    */

          /*
           * Oh, and I haven't shown shutdown recently....
           */
          RemoveCurrentProgram(NULL);   /* removes the process and the
                                           process' class as they were added
                                           as autoresources.
                                         */
          CloseLibrary(ShadowBase);
          .
          .
          .


     ArgumentTags

     The remaining mystical portion to methods (if you've been following
     everything else I've written) are the ARGUMENT_TAGs.

     ARGUMENT_TAGs describe the arguments that a method receives, above
     and beyond the nominal METHOD_ARGS, which ALL methods receive.
     While it is only the number and size of the arguments which
     interests the INVOKE_CALL and INVOKE_SYNC types of calls, the type
     of the argument is very important when invoking a method
     ASYNChronously -- this is how the arguments get properly resource-
     tracked across asynchronous tasks!  In addition, if resources are
     returned from an asynchronous invocation, they need to be thrown
     away -- the ARGUMENT_TAG provides for this behaviour as well.

     An ARGUMENT_TAG, therefore, comes in two parts -- the first part
     describes each of the arguments -- the type, the size that is
     required for them on the stack (yes, you can pass a structure
     to a method by-value), and any additional information that
     might be needed (the size of a pointer, the size of each element
     in an array, etc.).  The second part serves as both the ARGUMENT_TAG
     terminator (the TAG_END) and contains the information about the
     returned resource (the type and the additional information fields,
     the size on the stack is not applicable as DSM() only returns
     a single long-word value in d0).

     The following is taken from the AutoDoc for SetMethodArgs(), a
     function which you will not need to use in all likelihood, but,
     nevertheless, the place where information about ARGUMENT_TAGs
     was previously kept.  Note that the definition for the AttributeTag
     structure resides in <shadow/misc.h>:

      If the method-function returns a variable that needs to be kept
      track of, the last ArgumentTag structure (whose at_tag should be
      zero) in the array should contain information for async. method
      sends to safely deallocate or otherwise resource track the
      returned value.

      Valid returns are:
       SHADOW_RETURN_BLANK   0
       SHADOW_RETURN_OBJECT  1
       SHADOW_RETURN_STRING  2
       SHADOW_RETURN_PORT    3
       SHADOW_RETURN_TAGL    4
       SHADOW_RETURN_PTR     5
       SHADOW_RETURN_MRFO    6

      These values should be stored in the at_size field of the last
      ArgumentTag array item..

      For SHADOW_RETURN_PTR, the size of the pointer should be stored
      in the at_flags field of the same item, for SHADOW_RETURN_TAGL,
      the size of each array item should be stored in the at_flags field
      of this last item, and for SHADOW_RETURN_MRFO, the offset of the
      returned data from the object in question should be placed in the
      at_flags field

      Normally, that is, in every case except the last item, the system
      supports a number of at_tag values:
         'MRFO':
            used for object values which add at_flags to
                  the passed object pointer.
            at_size should be four
            at_flags -- the offset of the passed data from the object ptr.

            Note that MRFO exists for system use, however you are free to
            use the item as well -- but it's of little to no use, just
            pass the object instead!

         'JOBJ':
            Used for an object.
            at_size should be four
            at_flags should be one of:
               SHADOW_OBJECT
               SHADOW_CLASSLESSOBJECT
               SHADOW_META
               SHADOW_CLASS,
               SHADOW_CLUSTER
               SHADOW_COMPOSITE
             though this is more for peace of mind than necessity.

         'JMSG':
            Used for a message creted by MessageMaker()
            at_size should be four
            at_flags should be zero

         'JSTR':
            Used for a system string.
            at_size should be four
            at_flags should be zero

         'PORT':
            Used for a ppipc port.
            at_size should be four
            at_flags should be zero

         'TAGL':
            Used for a NULL terminated array.
            at_size should be four.
            at_flags should be the size of each array item

         'RTRN':
            reserved by the system, don't use.
         'APTR'
            a pointer to some memory.
            at_size should be four.
            at_flags should be zero if you don't want to copy the data to
             another block when sending async., or should be the size of
             the data pointed to if you do.

         Create you own 4 character constant:
            at_size should be an even number -- you can pass arbitrarily
             large structures on the stack, this way.
            at_flags ignored.


     If we examine closely, a few limitations crop up.  For one thing,
     there doesn't seem to be a way to add another "type" of argument that
     would require a different kind of resource-tracking.  This is TRUE --
     please send me your requests!

     Second, you can't pass a structure pointer that point to a structure
     of more than 65535 bytes (at_flags is a UWORD value).  If you need to
     pass a 64k or bigger structure, feel free to prepend the three
     long-word values which would be required for a struct
     ClasslessObject, set the classless object's size to the final size of
     the larger structure, and pass the large structure as an object.
     The structure will thus not be copied between asynchronous tasks
     (saving time and space).  If you need to copy the object, use the
     original structure (without the struct ClasslessObject header) in a
     call to CreateObject() like this:

          newObject = CreateObject(bigStructurePointer,
                                   sizeof(BigStructure));

     This will create a new ClasslessObject structure with the values found
     in the passed bigStructurePointer copied into the returned object.
     The method call would proceed:

          DoShadowAsync(object, NULL, SOME_METHOD, newObject, METHOD_END);
          /*
           * No Longer need this!
           */
          DropObject(newObject);

     Similarly, the array item in a TAGL can not be larger than 65k.  The
     array can be larger, just not each individual item....


     The following example introduces ARGUMENT_TAGs in a real-world
     application.  The code is analogous to the METH_INIT code for the
     ROOT_CLASS.  This method (as the browser indicates) takes a single
     parameter -- a 'JSTR'.  This string is used to add the object to
     some kind of global (avl) tree structure.  If the string is NULL,
     then the object's address is used instead.  For the ROOT_CLASS'
     METH_INIT, the global tree ends up being the object's class'
     ATTR_INSTANCETREE tree, not a global tree as in this example:

          METHOD_TAG carMethods[] = {
                                        .
                                        .
                                        .
                                        {
                                           METH_CAR_REGISTER
                                           NULL, NULL,
                                           SHADOW_MSG_CALL,
                                           METHOD_FLAG_PROC, 0,
                                           RegisterCarMethod,
                                              REF_RegisterCarMethod
                                        },
                                        TAG_END
                                     };


          .
          .
          .
          /*
           * The MY_CAR_CLASS methods.
           *
           * METH_CAR_REGISTER:
           */
          ARGUMENT_TAG  REF_RegisterCarMethod[] =
                           {
                              {'JSTR', 4, 0}, /* The one argument */
                              {TAG_END, SHADOW_RETURN_OBJECT, 0}
                                              /* The return spec. */
                           };
          OBJECT RegisterCarMethod(METHOD_ARGS, char *string)
          {
             /*
              * This method "swallows" the object passed in and
              * either returns or removes it.  Therefore, we must
              * transfer the object out of any asynchronous messages
              * we might receive.
              *
              * The "0" is used because "object" is the "zeroth"
              * argument to this method.  "class" is first, "MethodID"
              * is second, "string" is third, etc.
              */

             IPCARGTransfer(msg, 0);

             /*
              * If there is a name, add the object to the tree with that
              * name, otherwise add the object using the object's address.
              */
             if ((!string && AddWatchedTreeNode(globalTree
                                                object,
                                                (long)object)) ||
                 (string && AddWatchedTreeStringNode(globalTree,
                                                     object,
                                                     string)))
             {
                return object;
             }

             /*
              * Failure case, cleanup!
              */
             RemoveObject(object);
             return NULL;
          }

          .
          .
          .

          /*
           * Creating the MY_ROOT_CLASS
           */
          SetupMethodTags(rootMethods, (void *)-1, (void *)-1);
          myRoot = CreateSubClass(NULL, ROOT_CLASS, META_CLASS,
                                                    MY_CAR_CLASS,
                                                    NULL,
                                                    NULL,
                                                      /* No new attrs */
                                                    rootMethods,
                                                    METHOD_END);

          AddAutoResource(NULL, myRoot, MY_ROOT_CLASS);
          .
          .
          .
          /*
           * No Cleanup necessary!
           * Just call RemoveCurrentProgram() and get out!
           * The MY_ROOT_CLASS wil be -terminated- automagically.
           */
          RemoveCurrentProgram(NULL);
          CloseLibrary(ShadowBase);
          .
          .
          .


     This example uses one argument specification -- a 'JSTR' -- and
     then specifies that the method returns an object.  We can call
     this method using the following (assuming this code is run
     somewhere between the CreateSubClass() and the
     RemoveCurrentProgram() calls in the above code example!):

          /*
           * Create the object
           */
          auto = CreateInstance(NULL, MY_ROOT_CLASS, META_CLASS,
                                                     METHOD_END);

          /*
           * Send off the method.
           */
          auto = DoShadow(auto, NULL, METH_CAR_REGISTER, METHOD_END);

                    -or-

          auto = DoShadow(auto, NULL, METH_CAR_REGISTER, "some object",
                                                         METHOD_END);
          /*
           * Cleanup!
           */
          RemoveObject(auto);


     This method is also safe to call asynchronously!

          DoShadowAsync(auto, NULL, METH_CAR_REGISTER, "some object",
                                                       METHOD_END);

          /*
           * Cleanup!
           *
           * It is possible for the METH_REMOVE method to be called
           * twice in this case....
           */
          RemoveObject(auto);


     Indeed, ARGUMENT_TAGs are most heavily used for the asynchronous case.
     The DoShadowAsync() attempts to invoke an asynchronous method on the
     auto.  This causes DSM() to create an IPC message with several items
     of interest -- the auto object, the string argument, and the return
     value are the only items that matter for this example.

     The auto object has its cob_UseCount incremented via UseObject().
     The string argument is created with the UseString() call.
     The return value is set to return an object (specifically, the
     ipc_Id is set to 'JOBJ').  The message is then sent off to the
     destination process.

     When the destination process receives the message, the method ends
     up being called (within ParseShadowMessage()).  The method
     specifically removes the "object" (the "auto") from the message.
     This method is defined as "swallowing" the auto-object, so the
     message is updated to reflect this.  The "auto" is then added to some
     globalTree.  If the addition is successful, the "auto" is returned.
     Otherwise the "auto" is Remove()'d from the system.

     When the auto is returned, it is placed into the return slot in the
     message.  ParseShadowMessage() then attempts to return the message.
     However, asynchronous messages do not have a ReplyPort, so
     ParseShadowMessage() ends up calling JunkIPCMessage() which destroys
     each item's reference and then destroys the message.

     In order, then, the return object is Drop()'d via DropObject(), the
     auto-object is ignored (remember the IPCARGTransfer()!), the
     string is Drop()'d via DropString(), and the message is destroyed.

     Note, if you hadn't specified the argument in the ARGUMENT_TAG,
     char *string would have ended up being 0x80000001 (or worse, if
     you had more arguments, those other arguments might be the return
     address of the function or stored registers, etc.).  It is very
     important that your ARGUMENT_TAG matches your method's actual
     parameter specification.  In addition, if your SHADOW_RETURN_*
     field is incorrect (or left unspecified), improper resource
     tracking of the return object might take place.  For instance, if
     the ARGUMENT_TAG were specified as follows:

          ARGUMENT_TAG  REF_RegisterCarMethod[] =
                           {
                              TAG_END
                           };

     Then the passed string would take on the value of 0x80000001 and the
     returned object in the asynchronous case would be "lost."  It would
     never be Drop()'d from the system, and thus repeated use of the
     function (asynchronous use!) would cause memory loss and
     possibly memory fragmentation.

     Many macros have been defined in <shadow/misc.h> which allows you
     to build ARGUMENT_TAGs more easily.  The correct
     REF_RegisterCarMethod[] would look as follows:

          ARGUMENT_TAG REF_RegisterCarMethod[] =
                           {
                              ARG_STR,
                              RET_OBJ
                           }

     Which is to say, one string argument, and the return of an object.

     Using these macros, we define an example which uses all of the
     important types of method arguments:

          ARGUMENT_TAG REF_RaceCarMethod[] =
                           {
                              ARG_OBJ,
                              ARG_STR,
                              ARG_TAGL(sizeof(struct TagItem)),
                              ARG_MESG,
                              ARG_PORT,
                              ARG_INT,
                              {'stuf', sizeof(struct StockCar), 0},
                              ARG_PTR(0),
                              RET_NORMAL
                           }

          /*
           * Note that the error message field is actually never
           * deleted, this should be done by the caller.  Note
           * also that deleting the message even after an
           * asynchronous method invocation works because the message
           * is -copied- for the asynchronous send, and then the copy is
           * magically deleted after the method-function is done
           * executing.
           *
           * ParseShadowMessage() is usually called with the
           * SHADOW_RETURN_MSG_NEVER, but this is an example of an
           * alternative usage pattern.  Please refer to the AutoDocs
           * for more information about ParseShadowMessage()'s flags.
           */
          BOOL RaceCarMethod(METHOD_ARGS,
                             OBJECT registry,
                             char *name,
                             struct TagItem *tags,
                             struct IPCMessage *error,
                             struct IPCPort *port,
                             long failure_probability,
                             struct StockCar sc,
                             void *garbage)
          {
               if (!...use all the arguments to race the car...)
               {
                  if (port && error)
                  {
                     error->ipc_Msg.mn_ReplyPort = GlobalReplyPort;
                     if (PutIPCMessage(port, error);
                     {
                         /*
                          * A simplified version of code to retrive
                          * the message back from the error handling port.
                          */
                         WaitPort(GlobalReplyPort);
                         GetMsg(GlobalReplyPort);
                     } else
                        ParseShadowMessage(error,
                                           SHADOW_RETURN_MSG_ALWAYS);
                  } else if (error)
                     ParseShadowMessage(error, SHADOW_RETURN_MSG_ALWAYS);
                  return FALSE;
               }
               return TRUE;
          }


     There are four specific things I want to mention with this example.
     First, the ARG_TAGL need NOT have an item size identical to the
     size of struct TagItem.  Any array of items whose last item begins
     with a zero longword is considered a valid ARG_TAGL.

     Second, the ARG_MESG parameter is a message which holds a "preparsed"
     version of a method call.  You can create a message to pass into
     this method by using the following as an example:

          errorMessage = PreParseShadow(car, NULL, METH_CAR_ERROR,
                                        "Bad Race!",
                                        METHOD_END);

     The errorMessage contains a message which can be sent to another port
     or Parse()d out at some later time.  The METH_CAR_ERROR method is not
     actually called; the returned message, however, contains all the
     pertinent information to call the method if you later decide to.  To
     get rid of the message, you can either call ParseShadowMessage:

          ParseShadowMessage(errorMessage, SHADOW_RETURN_MSG_NEVER);

     which will invoke the method, and then destroy the errorMessage; or
     you can call JunkIPCMessage to destroy the message:

          JunkIPCMessage(errorMessage);

     Third, the "('stuf', sizeof(struct StockCar), 0}" is an example of
     how to pass large structures on the stack to a method.  To operate
     properly on 68000 based machines, the sizeof() had better be even.
     For best performance, it should be at least long-word aligned.

     Lastly, the ARG_PTR(0) means to pass a pointer to the function, but
     not to copy the data to another pointer if resource tracking would
     have normally required it (ie: asynchronous methods).  If you wanted
     to pass the StockCar structure in by pointer instead of on the
     stack, you could conceivably use:

          ARG_PTR(sizeof(struct StockCar)),

     instead of:

          {'stuf', sizeof(struct StockCar), 0},

     and define the method as

          ., /* Args deleted! */
          .,
          .,
          struct StockCar *sc,
          void *garbage)

     instead of:

          ., /* Args deleted! */
          .,
          .,
          struct StockCar sc,
          void *garbage)

     This alternative should run faster than requiring stack copying as in
     the original example.


     Assumeing you had an object of the correct class, the original method
     invocation might look as follows:

          errorMsg = PreParseShadow(car, NULL, METH_CAR_ERROR,
                                        "Bad Race!",
                                        METHOD_END);

          tags[0].ti_Tag = CAR_FORMULA;
          tags[0].ti_Data = 2;
          tags[1].ti_Tag = TAG_END;
          DoShadow(car, NULL, METH_CAR_RACE, registration, "Road Runner",
                   tags, errorMsg, NULL, 85, myStockCarStructure, NULL,
                   METHOD_END);
          JunkIPCMessage(errorMsg);

     This would work regardless of whether the method was defined to run
     synchronously (as a function call or a synchronous message) or
     asynchronously.  This independence allows you to create code that
     will run in a wider array of circumstances, and allow you to further
     tune your application by running various parts of your program in
     separate processes.


     CreateInstance:

     I have been using some wrapper functions in all of my method
     discussions -- CreateInstance and CreateSubClass.  In reality, they
     are really method calls.  CreateInstance() actually contains two
     methods as in the following pseudo-code:

          CreateInstance(privateClass, className, metaName, <..args..>)
          {
             OBJECT obj;

             if (!UseObject(privateClass))
             {
                created = TRUE;

                if (metaName)
                   privateClass = FindInstanceOfMeta(className, metaName);
                else
                   privateClass =
                    FindNodeWatchedTree(&ShadowBase->sb_metaTree,
                                        metaName);
             }

             /*
              * Create the object's memory.
              */
             obj = DoShadow(privateClass, NULL, METH_CREATE, METHOD_END);
             DropObject(privateClass);

             /*
              * Make it a real object.
              */
             ret_val= DoShadow(obj, NULL, METH_INIT, <..args..>);
             return ret_val;
          }

     The first method (METH_CREATE) actually creates memory for the
     object to exist in.  In addition, it sets up the class pointer for
     the object.  However, it is not, at this point, a valid object.  Were
     something to fail here, or in the METH_INIT, the only way to get the
     object to actually go away is to do the following:

          DropObject(UseObject(obj));

     This is in direct contrast to the normal "DropObject(obj)" that is
     usually called.  Programmers of METH_INIT take note!  The
     METH_DESTROY is only called when the usecount falls to zero.
     However, if it is zero to begin with (as, say, it is when it
     returns from the METH_CREATE method), you must first increment
     the usecount, and -then- decrement it.

     It is the METH_INIT that follows which is responsible for setting
     up the usecount to properly be non-zero.  And, of course, to setup
     the object correctly.


     The CreateSubClass is a simpler wrapper that ends up calling the
     METH_SUB method of a particular class.  The "privateClass" pointer
     lookup is exactly the same in the CreateSubClass() as in the
     CreateInstance(); however, it is the METH_SUB method that actually
     invokes the METH_CREATE and the METH_INIT, not CreateSubClass()....

     Wrap-up of Methods:

     There are many ways to call methods besides DoShadow().  We have seen
     at least two examples -- DoShadowAsync() and PreParseShadow().  The
     alternatives are documented in the ShadowLibFuncs.doc.  In
     addition, the root SHADOW library code for all of these functions is
     DSM(), and that is documented in ShadowLibraryFuncs.doc (autodoc).  I
     highly recommend using these references to learn more about the
     method invocation code.  We are about to go on to the more advanced
     topics of PATCHER_CLASS, PROCESS_CLASS and DIRECTOR_CLASS which will
     introduce even more complexity into an already complex picture, this
     is a convenient break point to try some example code and see what
     happens (let me know of any bugs!).  It will allow you to get a feel
     for the programming environment that SHADOW lives within and will
     make you feel more comfortable about the next three topics.



                              PATCHER CLASS

     You will notice that in the above discussion about methods there were
     several METH_FLAGS_* that were never covered and left later for the
     discussion about PATCHER_CLASS.  Well, the time has come.

     Yes, that's right, just as you thought you were beginning to
     understand everything about SHADOW's methods, some new twist pops up
     to confuse the issue.  PATCHER_CLASS is a rather good example of
     this.

     Essentially, all methods within all SHADOW classes are patchable.
     Patching is analogous to SetFunction(), except that great pains have
     been taken to assure that the problems with SetFunction() are NOT
     shared by PATCHER_CLASS.  Unfortunately, you also lose some of the
     flexibility of SetFunction().

     When a method is patched, the result is referred to as a
     "patch-chain."  DSM(), along with all of its other duties, is
     responsible for traversing the patch-chain and calling each of the
     separate method patches in turn and returning the most-recent, valid
     return value.

     Each patch is created in very nearly the same manner that the base
     methods were created -- through the use of the METHOD_TAG structure.
     Note, however, that each patch will require ONLY ONE METHOD_TAG
     item -- please do not attempt to pass single METHOD_TAG *items* to
     functions like SetupMethodTags() which requires a METHOD_TAG *array*.
     This will not work, so you'll have to setup the mtag_procObject and
     mtag_defnObject fields by hand (or put all of your METHOD_TAG patches
     in one big array and call SetupMethodTags() on this array.

     There are two significant differences between the METHOD_TAGs that
     are used for the base methods and the METHOD_TAGs that are used for
     patches.  The former ignores the mtag_priority field while the
     latter uses it to order the patch-chain.  The patches in the patch
     chain are called in descending numerical order where the base
     method is always assumed to exist at priority zero.

     The second difference is the additional mtag_flags values which,
     while supported by the base methods, gain real power only when
     patch-chains exist:

          METH_FLAG_PRE_BLOCK
          METH_FLAG_POST_BLOCK
          METH_FLAG_CHECK_CONTINUE
          METH_FLAG_NO_RTRN


     METH_FLAG_PRE_BLOCK:
     If this flag is set, DSM() will stop invoking the patches within the
     patch-chain.  Additionally, the patch/base-method itself will not
     get invoked.  This is useful if you want to interrupt your
     patch-chain during the debugging phase, or if you want to disable
     some of the features in a demo version -- simply add the PRE_BLOCK to
     the base methods' mtag_flags, or add a PRE_BLOCK'd patch at some
     relatively high priority to the class to be affected.

     METH_FLAG_POST_BLOCK:
     If this flag is set, DSM() will stop invoking the patches within the
     patch-chain, but only after invoking this patch/base-method.  This is
     useful for replacing a base-method during a bug-release update.  Add
     a POST_BLOCK'd patch to the base-method at a priority greater than
     zero and the base-method is effectively replaced by the patch.

     METH_FLAG_CHECK_CONTINUE:
     If this flag is set, the patch returns an additional value in d1 which
     informs DSM() whether or not to continue the patch.  This allows you
     to dynamically change whether your patch executes, or the base-method
     executes.  If d1 is returned as zero from the patch, then the
     patch-chain invocation ends and the latest, valid return value is
     returned.  Otherwise, the patch-chain continues as it would have.

     METH_FLAG_NO_RTRN:
     This informs DSM() that your patch or method does not return a valid
     value, so any previous return values that have accumulated while
     traversing the patch-chain should remain intact.  Note that this is
     a significant inversion of meaning from SHADOW 4's
     METHOD_FLAG_RTRN_ME.


     Several important notes should be made at this point.  First, the
     traversal through the patch chain is controlled by a semaphore on the
     patch-chain's list.  This means that if you attempt to do something
     silly like have a base-method which patches itself, or a patch/base-
     method which attempts to remove a of the patch, the semaphore will
     nicely lock up your code.  Secondly, the traversal through the
     patch chain is guaranteed to be serial.  This means that even
     if you call DoShadowAsync(), the method will actually be preparsed,
     sent to the base-method's mtag_procObject asynchronously, and only
     then will the patch-chain invocation will occur.  This allows
     behaviour which depends on serial traversal (like the
     FLAG_CHECK_CONTINUE) to continue to operate correctly, even though
     each patch is actually invoked asynchronously to the invoker.

     Third, while patches are invoked from high priority to low priority,
     the actual return value will be the return value from the -lowest-
     priority patch that ended up returning a valid return value.  Fourth,
     the method that is being patched must ALREADY exist within the class
     that's being patched -- the only way to add new methods is to modify
     the superclass hierarchy -- this will be covered at the end of the
     PATCHER_CLASS description.  Fifth, there is a speed penalty to using
     patch-chains -- do not expect them to ever be very speedy.  And last,
     but certainly not least, because DSM() controls the patch-chain
     traversal, there is no way to modify the arguments as they travel
     from patch to patch.  Please be careful and act accordingly.


     The following code demonstrates the PATCHER_CLASS in action:

          /*
           * The patches
           */
          extern double PreTestMethod(METHOD_ARGS);
          extern long PostTestMethod(METHOD_ARGS);

          METHOD_TAG preMethod =
                                     {
                                        "Method TEST",
                                        NULL, NULL,
                                        INVOKE_SYNC,
                                        METH_FLAG_CHECK_CONTINUE |
                                        METH_FLAG_CLASS |
                                        METH_FLAG_NO_RTRN,
                                        1, /* The priority */
                                        (METHODFUNCTYPE)PreTestMethod,
                                           NULL
                                     };

          METHOD_TAG postMethod =
                                     {
                                        "Method TEST",
                                        NULL, NULL,
                                        INVOKE_SYNC,
                                        METH_FLAG_OBJECT |
                                        METH_FLAG_NO_RTRN,
                                        -1,
                                        (METHODFUNCTYPE)PostTestMethod,
                                           NULL
                                     };

          /*
           * Add pre and post patches to the dosClass.
           * Note that the "Method TEST" method MUST ALREADY exist
           *  in the dosClass definition.
           */
          preMethod.mtag_procObject = dosTaskClass;
          preMethod.mtag_defnObject = CurrentProcess();

          preObject = CreateInstance(NULL, PATCHER_CLASS, META_CLASS,
                                                          &preMethod,
                                                          dosClass,
                                                          METHOD_END

          postMethod.mtag_procObject = dosTask;
          postMethod.mtag_defnObject = CurrentProcess();

          postObject = CreateInstance(NULL, PATCHER_CLASS, META_CLASS,
                                                           &postMethod,
                                                           dosClass,
                                                           METHOD_END);


          /*
           * The method has now been patched!
           * Now, when you call the method, the preMethod is invoked in an
           * instantiated dosTaskClass-process; then the regular method is
           * invoked; then the postMethod is invoked synchronously in the
           * dosTask process.
           */
          .
          .
          .
          /*
           * Remove the patches.
           * You could have added this to the process with the
           *  AddAutoResource() call, in which case you would not
           *  need to call RemoveObject()....
           */
          RemoveObject(preObject);
          RemoveObject(postObject);



         /*
          * The patcher methods.
          *
          * The PreTestMethod() uses a SAS/C 5.0 side-effect where
          *  a double is returned in d0 and d1.
          * Whether the patch-chain continues or not alternates
          *  between TRUE and FALSE.
          */
          double PreTestMethod(METHOD_ARGS)
          {
             static int __far myLocalVar = 0; /* YES -- __far is
                                                        required! */
             union {
                double tempD;
                ULONG  tempV[2];
             } retval;
             BPTR oldoutput;

             oldoutput = SelectOutput(Open("CONSOLE:", MODE_OLDFILE));

             VPrintf("Pretest called in <%s> task.\n",
                     (ULONG *)&(FindTask(NULL)->tc_Node.ln_Name));

             if (!(retval.tempV[1] = (myLocalVar++ & 1)))
                VPrintf("PreTest will block this call:\n", NULL);

             oldoutput = SelectOutput(oldoutput);
             Close(oldoutput);
             retval.tempV[0] = 0;  /* This number is NOT a valid return!
                                    * Note the METH_FLAG_NO_RTRN
                                    */
             return retval.tempD;
          }

          /*
           * Note that the "return 200" is NOT a valid return as the
           * METHOD_TAG has the METH_FLAG_NO_RTRN flag set.
           *
           * As the preMethod and the postMethod never return a
           *  valid return value, the return value of the base-method
           *  is returned, -if- the preMethod doesn't return a FALSE (which
           *  would end the patch-chain, and therefore prevent the base-
           *  method from being called in the first place.  In that case,
           *  the DSM() [DoShadow(), et. al.] returns zero.
           */
          long PostTestMethod(METHOD_ARGS)
          {
             VPrintf("Post test called\n", NULL);
             return 200;
          }


     While PATCHER_CLASS allows you to patch existing methods, it does not
     allow you to add additional methods.  There is a way to add methods
     to a class, unfortunately, there is no way to later -remove- those
     methods.  The way in which this occurs is to change the superclass
     hierarchy so that the class that you want the method to be added to
     is changed to be a subclass of a class that is created with the
     method you desire.

     In otherwords, if you wish to add a method to the PROCESS_CLASS,
     you create an intermediate class with the additional method, then
     point the superclass of the PROCESS_CLASS to the intermediate class.
     It is, of course, required that the intermediate class be a subclass
     of the superclass of the "PROCESS_CLASS", or, the class your adding
     the method to.  You can use the SHADOW library function call --
     InsertSuperClass(), or the METH_SUPER method call as demonstrated
     below:

          /*
           * Creates a new superclass of a subclass.
           * Adds the methods specific in the my_new_method structure.
           */
          procClass = FindShadowClass(PROCESS_CLASS, META_CLASS);
          newClass = DoShadow(procClass, NULL, METH_SUPER,
                              MY_INTERMEDIATE_CLASS,
                                          NULL,
                                          my_new_attributes,
                                          my_new_methods,
                                          METHOD_END);
          DropObject(procClass);

          .
          .
          .

          RemoveObject(newClass);


     This example is taken directly from the ShadowLibraryMethods.doc,
     where you can find more information about the METH_SUPER method.  In
     addition, you can find out more about adding new methods by reading
     the InsertSuperClass() method.

     Obviously, the preferred manner of adding methods to classes is to
     -subclass- them and create your own classes.  However, PATCHER_CLASS
     exists to provide as much flexibility and extensibility as possible.


                             DIRECTOR CLASS

     DIRECTOR_CLASS expands upon the notion of extensibility by providing
     notification for important system and program state changes.  For
     instance, you can receive notification whenever a class is added
     or removed from the system list, or when a -particular- class is
     added or removed from the system.  In the gui I've been
     experimenting with, the ATTR_GUICHILDREN attribute which is a
     "watched" binary tree that contains a GUI-object's children,
     generates notification whenever any children are removed or
     added to the system.

     In addition to being able to watch a particular GUI-object, you can
     watch all the GUI-object's of any particular class (and associated
     subclasses) that you'd like.  It is entirely feasible to imagine
     receiving notification whenver any program added any GUI-object to
     the child tree of any other GUI-object.

     DIRECTOR_CLASS objects handle the request for notification of these
     system and program state changes.  These state changes occur in
     special kinds of "state" or "watched" variables.  You can create a
     WatchedVariable in the following manner:

     void *nullPtr = NULL;
     struct WatchedVariable   wv = {NULL, &nullPtr, initial_value};

     The &wv can then be used when establishing a connection in
     the DIRECTOR_CLASS.  However, as SHADOW is mainly an object-
     oriented system (or, rather, it seems to have grown into being one),
     it is more frequent to find yourself establishing a director-object
     connection to a watched variable inside of a class.

     A watched variable inside of a class is created in a very special
     way that allows you not only to watch a single object, but all the
     objects that are instances of a particular class (and instances of
     all classes that are subclasses of that particular class).

     Here is an example attribute definition:

          ATTRIBUTE_TAG guiAttrs[] =
                     {
                        {
                           ATTR_GUICHILDREN, FLAG_ATTR_WATCHED |
                                             SHADOW_TREE,
                           NULL
                        },
                        TAG_END
                     }

     This attribute creates a watched variable that allows you to use
     the attribute as an AVL tree.  Although, instead of calling the
     regular AddTreeNode() and/or RemoveTreeStringNode(), you call the
     AddWatchedTreeNode() and/or RemoveWatchedTreeStringNode().  As a
     director watching this attribute, you can get notification about
     when a node is added or removed from the tree (you can also
     receive notification when some other director establishes or
     terminates a connection to any watched variable, but that gets
     just a little ridiculous...).

     There are three basic types of watched variables.  One is the
     long-word type, another is the AVL tree type which is shown
     above, and the last is the singly-linked list type which I
     won't bother to cover in the examples.  These three types
     are denoted by three different flags located in <shadow/watcher.h>:
          SHADOW_VALUE
          SHADOW_TREE
          SHADOW_LIST
     Use these flags in the ATTRIBUTE_TAG value when creating a
     watched variable in an object.

     Watching a watched variable is a two-step process.  First you
     need to create an instance of a director class.  There are several
     things to setup at this phase -- the name of the director
     object, the object that will receive the notification and the
     selector that will be invoked on that object, the type of events
     you want to receive notification about, the type of watcher, and
     the default resource tracking cleanup algorithms that will be
     used when the director's connections are terminated and the
     director is removed from the system.

     Second, you need to extablish a connection with a particular watched
     variable/attribute or class of watched attributes.  Unlike method
     patches which are can only be installed in a single class at a time,
     director objects can establish themselves in any number of watched
     variables -- allowing you to save, perhaps, a bit of memory in the
     process....  The ESTABLISH method only takes arguments which
     defines the watched variable and returns a handle to the connection
     which should either be sent to DropObject(), or used in any
     explicit call to the METH_DIRECTOR_TERMINATE method.

     Setting up a director object is less complex than method patches, but
     nevertheless there are a few flags you should know about [the
     following flags are located in <shadow/watcher.h>]:

          /*
           * Match either.
           */
          W_CHANGE_ZERO
          W_CHANGE_NON_ZERO
          W_CHANGE_VALUE

          /*
           * Match exactly
           */
          W_NODE
          W_WATCH_CHANGE
          W_REMOVE
          W_INSERT

          /*
           * Control matching.
           */
          W_MATCH
          W_MATCH_VALUE      W_MATCH
          W_SECOND

          W_MATCH_FIRST      W_MATCH
          W_MATCH_SECOND     (W_SECOND | W_MATCH)

          W_INSERT_NODE      (W_NODE | W_INSERT)
          W_REMOVE_NODE      (W_NODE | W_REMOVE)

          W_INSERT_WATCHER   (W_WATCH_CHANGE | W_INSERT)
            /* Not valid during... */
          W_REMOVE_WATCHER   (W_WATCH_CHANGE | W_REMOVE)
            /* ... INIT[]/DESTROY[]  */

     The exact meaning of all of those flags is covered in detail under
     the METH_DIRECTOR_NOTIFY method description in ShadowMethods.doc.
     In general, these flags describe which state-change events the
     director object is interested in getting notification about.

          /*
           * for use in passing to METH_INIT....
           */
          W_FLAG_AUTOBREAK
          W_FLAG_AUTOREMOVE


     Do -not- confuse these with the W_AUTOBREAK and W_AUTOREMOVE flags
     which are NOT to be passed into the METH_INIT function!
     The W_FLAG_AUTOBREAK informs the director object that when the
     director is sent a METH_REMOVE method, it should terminate all of
     its outstanding connections.
     The W_FLAG_AUTOREMOVE informs the director object that when the
     last connection is terminated, the director should automatically
     be removed from the system.
     By default, I suggest you use both flags unless you think of some
     -very- good reason not to.

          W_OBJECT
          W_CLASS

     These two flags specify which type of director you wish to create --
     one to watch an entire class, or one to watch just a specific
     object or watched variable.


          /*
           * As flag to TERMINATE METHOD.
           */
          W_HANDLE
          W_SORT

     There are three ways to TERMINATE a connection.  The first is to
     create the director with the W_FLAG_AUTOBREAK flag set and then
     send a METH_REMOVE method (ie. RemoveObject()) to the director.
     This will terminate all connections.  The second is to specify,
     using the handle returned to you by the ESTABLISH call, a specific
     connection be TERMINATEd.  This is the W_HANDLE case, and if left
     unspecified, the default manner is W_HANDLE.  The third case is to
     specify an object that the director was watching and TERMINATE any
     connection in that object -- however, you are not guaranteed
     -which- connection is terminated, if you are watching more than one
     attribute, or one attribute more than once, or some combination
     thereof.  This third possibility is usually used by the system,
     rather than the external programmer -- there are very arcane
     reasons for why this needs to exist....


     There are two different types of directors -- class-watchers and
     object-watchers.  Herein we demonstrate both:

          /*
           * Create a director object.
           *    Specify the director's name as "WatchWindows".
           *    Specify the notification be invoked on "object" with the
           *       METH_TELL_ME method.
           *    Specify interest in addition or removal of nodes from a
           *       complex watched variable like SHADOW_TREE or SHADOW_LIST
           *    Specify a class watcher
           *    Specify the autoremove and autobreak features.
           */
          GlobalDirector = CreateInstance(NULL,
                                          DIRECTOR_CLASS,
                                          META_CLASS,
                                          "WatchWindows",
                                          object,
                                          METH_TELL_ME,
                                          W_INSERT_NODE | W_REMOVE |
                                           W_CLASS |
                                           W_FLAG_AUTOBREAK  |
                                           W_FLAG_AUTOREMOVE,
                                          METHOD_END);

          /*
           * Let's watch for additions and removal of children to any
           * object of the WINDOW_CLASS, or any instance of any
           * subclass of the WINDOW_CLASS....  The watched-tree
           * attribute that contains the windows' children is
           * called ATTR_GUICHILDREN.  It is not specific to just the
           * WINDOW_CLASS, though....
           *
           * Note that we throw away the handle that the ESTABLISH
           * method returns.
           */
          windowClass = FindShadowClass(WINDOW_CLASS);
          DropObject(DoShadow(GlobalDirector,
                                  NULL,
                                  METH_DIRECTOR_ESTABLISH,
                                  ATTR_GUICHILDREN,
                                  windowClass,
                                  METHOD_END));
          DropObject(windowClass);


          .
          .
          .

          /*
           * Cleanup!
           * We didnt't add the GlobalDirector to our AutoResource() tree,
           * so we'll have to do an explicit RemoveObject()!
           * Remember, the W_FLAG_AUTOBREAK means that the METH_REMOVE
           * terminates all connections.
           */

          RemoveObject(GlobalDirector);


     The following example will demonstrate a director watching an object,
     or watching a plain watched variable that does not exist within an
     object:

          /*
           * Create a director object.
           *    Specify the director's name as "Watch Meta".
           *    Specify the notification be invoked on "object" with the
           *       METH_INFORM_ME method.
           *    Specify interest in addition or removal of nodes from a
           *       complex watched variable like SHADOW_TREE or SHADOW_LIST
           *    Specify an object/variable watcher
           *    Specify the autoremove and autobreak features.
           */
          mlo->director = CreateInstance(NULL,
                                         DIRECTOR_CLASS,
                                         META_CLASS,
                                         "Watch Meta",
                                         object,
                                         METH_INFORM_ME,
                                         W_INSERT_NODE | W_REMOVE |
                                          W_OBJECT << 16 |
                                          W_FLAG_AUTOBREAK |
                                          W_FLAG_AUTOREMOVE,
                                         METHOD_END);

          /*
           * If there is a specific 'meta' to watch, let's watch
           * for additions or removals of instances to/from the meta's
           * ATTR_INSTANCETREE.  If there is no meta (that is, if meta
           * is NULL), let's watch SHADOW's public Watched Variable
           * which contains all the current metas and watch for a
           * meta to be added or removed.
           *
           * Note that we throw away the handle that the ESTABLISH
           * method returns.
           *
           * Note, we pass in the object and the object's attribute
           * that we want notification about (meta dn ATTR_INSTANCETREE
           * in this case.  If the object is NULL, the attribute, which
           * is usually a string, is now assume to point to a watched
           * variable structure instead.
           *
           * Yes, we really want a W_OBJECT watcher to watch a meta.
           * Why?  Because we are watching -one- meta, not a whole
           * *class* of metas, which is where we would want to use a
           * W_CLASS type of director.  In otherwords, if you wanted to
           * watch the ATTR_INSTANCETREE of a  whole class of metas,
           * you'd use a W_CLASS.  Here, though, we need a W_OBJECT
           * director object.
           */

          DropObject( DoShadow(mlo->director,
                               NULL,
                               METH_DIRECTOR_ESTABLISH,
                               (meta)?ATTR_INSTANCETREE:
                                     &ShadowBase->sb_metaTree,
                               meta,
                               METHOD_END));


          .
          .
          .

          /*
           * Cleanup!
           * We didnt't add the mlo->director to our AutoResource() tree,
           * so we'll have to do an explicit RemoveObject()!
           * Remember, the W_FLAG_AUTOBREAK means that the METH_REMOVE
           * terminates all connections.
           */

          RemoveObject(mlo->director);


     For this example, we explore explicit TERMINATion of a director's
     connections.

          /*
           * Create a director object.
           *    Specify the director's name as "WatchBlockedChildren".
           *    Specify the notification be invoked on "object" with the
           *       METH_SLAP_ME_ONCE method.
           *    Specify interest in addition or removal of nodes from a
           *       complex watched variable like SHADOW_TREE or SHADOW_LIST
           *    Specify an object/variable watcher
           *    Specify the autoremove and autobreak features.
           */
          director = CreateInstance(NULL,
                                    DIRECTOR_CLASS,
                                    META_CLASS,
                                    "WatchBlockedChildren",
                                    object,
                                    METH_SLAP_ME_ONCE
                                    W_INSERT_NODE | W_REMOVE |
                                     W_OBJECT << 16 |
                                     W_FLAG_AUTOBREAK |
                                     W_FLAG_AUTOREMOVE,
                                    METHOD_END);

          /*
           * Establish the connection for the director.
           * Here, we'll watch the ATTR_GUICHILDREN of an object.
           */
          handle1 = DoShadow(director, NULL, METH_DIRECTOR_ESTABLISH,
                                             ATTR_GUICHILDREN,
                                             object,
                                             METHOD_END);

          /*
           * Establish another connection.
           * Here, we'll watch the ATTR_INSTANCETREE of WINDOW_CLASS.
           * Note that we aren't interested in the INSTANCE_TREE
           * attribute for -all- classes, just for the on particular
           * -class-instance- -- WINDOW_CLASS, which is why we want
           * a W_OBJECT watcher as opposed to a W_CLASS watcher.
           */
          windows = FindShadowClass(WINDOW_CLASS);
          handle2 = DoShadow(director, NULL, METH_DIRECTOR_ESTABLISH,
                                             ATTR_INSTANCETREE,
                                             windows,
                                             METHOD_END);
          DropObject(windows);

          .
          .
          .

          /*
           * Terminate the first connection.
           */
          DoShadow(director, NULL, METH_DIRECTOR_TERMINATE, handle1,
                                                            METHOD_END);

          .
          .
          .
          /*
           * Terminate the second connection.
           */
          DoShadow(director, NULL, METH_DIRECTOR_TERMINATE, handle2,
                                                            METHOD_END);

          .
          .
          .
          /*
           * Cleanup!
           *
           * Note, because we specified the W_AUTOREMOVE feature, and
           * because we've closed all of the connections, the director
           * has already been removed.  Therefore, simply DropObject()
           * it.
           */
          DropObject(director);


     This code is taken directly from the Browser included in the SHADOW
     distribution.  Browser uses W_OBJECT watchers to maintain a current
     list of the available classes, objects, and number of patches on a
     method.  If you add a class while the Browser is showing a list of
     the classes, that list is updated automatically, without the active
     knowledge of the program creating the class!



                              PROCESS CLASS

     Process classes offer several hurdles that are not encountered
     with any other objects.  First, the initialization of a process is
     primarily a two-stage procedure -- the creation of an AmigaDOS
     process, and then the initialization of all of the ports, libraries,
     etc. that that particular task requires.  Note that the second
     stage -must- occur within the created task, whereas the first
     stage -cannot- occur within that task (it wouldn't be around at
     that point).  Second, the cleanup of processes (ie: the removal
     of ports and libraries bases, etc.) must occur within the task
     itself, but cannot actually occur until all references to the
     process object are eliminated.  On the otherhand, many of the
     resources added to a process via the AddAutoResource() call
     reference the process object (usually indirectly, through
     an mtag_defnObject field in a method within a class, for instance).
     Therefore, the METH_REMOVE must clear all of the automatic
     resources, but the METH_DESTROY is responsible for actually
     closing down the ports, allocated signals, and library
     bases.

     Additionally, process creation must take into account that a program
     launched via the CLI or the Workbench does not have a SHADOW
     process object associated with it, and therefore does not contain
     the requisite ports and messages to deal with the sending and
     receiving of SHADOW methods.  There must be a way to associate
     an already existing process with a SHADOW process object after
     the process creation (note how similar this requirement is to
     the two-stage startup procedure described in the above paragraph).

     Finaly, processes should provide an example on how to properly deal
     with SHADOW messages by providing a default message handler which
     handles all of the various SHADOW methods and returns when the
     process gets a ^C (a ^C is automatically sent to the process by
     the system under certain shut-down conditions as well).


     Process and Program Startup and initialization

     The initialization of a process object is separated into two separate
     parts -- a METH_INIT and a METH_PROC_ASSOCIATE.  The METH_INIT
     takes several parameters:
          The name of the process
          One of two parameters that prevents a parent process from
             exitting before its children
          A taglist that is passed to the CreateNewPoc() AmigaDOS call
          A ProcessInitFrame    -- for the METH_PROC_ASSOCIATE call
          A ProcessHandlerFrame -- for the METH_PROC_HANDLER call

     Let's take them one at a time, ignoring the process name argument,
     as its function is obvious.

     Let us say that you start a thread on one of your processes.  You
     definitely do not want your parent process going away before your
     child threads have all disappeared -- there are two ways to prevent
     this.  First, you can pass an Exec semaphore pointer to the
     INIT code.  The thread that is created will grab a SHARED lock on
     this semaphore between the time that the METH_INIT is called,
     and the time when the METH_INIT returns (the magic involved therein
     is unimportant).

     Therefore, before your parent process disappears, it should attempt
     to grab an exclusive lock on this semaphore.  You can accomplish
     this by passing the semaphore into the RemoveCurrentProgram()
     call that all SHADOW programs call in their cleanup code.

     A much easier way (and the preferred SHADOW V way to deal with these
     issues) is to pass the parent's own process object into the the
     METH_INIT call.  SHADOW will then resource track the parent process
     within the child thread.  The parent process will be dropped only
     after the program returns from the _HANDLER routine, thereby
     preventing the parent process from disappearing before its children.

     The taglist is a taglist that is passed to the CreateNewProc()
     library call under AmigaDOS.  Several tags are reserved for
     exclusive use by SHADOW.  They are:
          NP_Name
          NP_ExitData
          NP_Entry

     NP_Name is set to the name passed into the INIT call.
     NP_ExitData is used internally.
     NP_Entry is used internally.  You should use the ProcessHandlerFrame
     to set your entrypoint -- this will be a -method- entry-point....

     The ProcessInitFrame is a METHOD_END-terminated array of the
     arguments that will be used to finish the creation of the process.
     If NULL, the internal definition of the arguments that
     METH_PROC_ASSOCIATE takes is used.  You may override which method is
     called to complete the process initialization by specifying a non-
     NULL field for the pif_methodID field.  If NULL, the method is
     assumed to be METH_PROC_ASSOCIATE.  In addition, you may add any
     number of arguments to the end of the InitFrame, though the
     final arguments should all be taken by the destination method.

     The following is the internal ProcessInitFrame that is used by
     SHADOW.  It resides in <shadow/process.h>:

          struct ProcessInitFrame {
             struct CoreObject *pif_object;
             struct Meta       *pif_class;
             char              *pif_methodID;
             char              *pif_procName;
             void              *pif_args[1];  /*
                                               * Other arguments,
                                               * terminated by METHOD_END
                                               */
          };


     The METH_INIT code fills in the object, and the class, and changes the
     methodID as required.  If the ProcessInitFrame is passed in, the
     pif_procName is not touched, and the rest of the arguments are
     assumed to be valid and terminated by a METHOD_END.  The entire
     array is passed to DSM() which returns a message encapsulating
     the appropriate method call.  The actual invocation of this
     method will occur once the process starts up.

     The ProcessHandlerFrame is the entry point (method) into the thread.
     By default, this is the METH_PROC_HANDLER method which takes no
     arguments.  As with the ProcessInitFrame structure, the actual
     method can be overrided by passing in your own methodID in the
     ProcessHandlerFrame.  A NULL methodID field in a passed
     ProcessHandlerFrame is assumed to mean METH_PROC_HANDLER.

     The following is the internal ProcessHandlerFrame that is used by
     SHADOW.  It also resides in <shadow/process.h>:

          struct ProcessHandlerFrame {
             struct CoreObject *phf_object;
             struct Meta       *phf_class;
             char              *phf_methodID;
             void              *phf_args[1];  /*
                                               * Other arguments,
                                               * terminated by METHOD_END
                                               */
          };

     Once again, either the default ProcessHandlerFrame, or one that you
     provide, is passed into DSM() and a message is returned.  During
     the internal startup code of the thread, the ProcessHandlerFrame's
     message is invoked subsequent to the ProcessInitFrame's message.

     Once both of these messages are created, the actual AmigaDOS process
     is created.  The METH_INIT will not return yet, though, the
     METH_PROC_ASSOCIATE (or the method specified in the ProcessInitFrame)
     is allowed to run first.  If this method returns 0L, then the
     initialization is assumed to have failed, the thread shuts down, and
     the METH_INIT returns a NULL process object.  If this method
     returns a non-zero value, the parent process is signalled to
     wakeup, and the thread calls the METH_PROC_HANDLER method (or
     the method specified in the ProcessHandlerFrame).

     When the parent process gets woken up, it attempts to discover
     whether or not the process ended up working or not, and if it did,
     the process object is returned, otherwise NULL is returned.  In
     addition, if your process is created, the tag entries are
     TAG_IGNORE'd -- this way you know whether you need to free any
     resources the tags might have pointed to (like file pointers for
     stdin and stdout).  Note that these fields are cleared whether or not
     the ProcessInitFrame method succeeded, the important point is
     whether or not the process was created.  After all, the process
     cleanup code that DOS runs cleans up stdin/out, etc....


     Much has been said about METH_PROC_ASSOCIATE -- that there is a
     method which is called (by default) by the new thread when the
     process is created, but very little has been said as to what it
     actually is supposed to do, and, no mention of hooking-up already
     existing processes with SHADOW process objects has been made.

     The METH_PROC_ASSOCIATE is the second stage of the two-stage process-
     creation procedure.  It is responsible for allocating ports for the
     new process object, opening up any libraries you might want opened,
     creating any additional ports (like an IDCMP port, for example)
     that you might want -- generally, any resource allocation that a
     process has to do up-front.  In addition, once all of this is
     successfully done, the METH_INIT method is forwarded from the
     PROCESS_CLASS to the ROOT_CLASS.  The process object, therefore, is
     not on any system lists until the METH_PROC_ASSOCIATE is called.
     Also, for your information, the process object is stored in the
     tc_UserData field of the process -- MAKE SURE YOU DON'T TOUCH IT!

     In addition, when a program starts, you are already given a process,
     but no SHADOW object exists for this process.  Creating a process
     object and calling METH_PROC_ASSOCIATE on it allows you to attach
     the AmigaDOS process to a SHADOW object, even after AmigaDOS has
     actually created the process.

     Startup in your program might look like this:

          ShadowBase = OpenLibrary("shadow.library", 5);
          if (!ShadowBase)
             abort_and_cleanse();

          procClass = FindShadowClass(PROCESS_CLASS);
          procObject = DoShadow(procClass, NULL, METH_CREATE, METHOD_END);
          DropObject(procClass);

          /*
           * an object has been created, now initialize it!
           * Note: procObject is swallowed by this call -- consider it
           *       never to have really existed as an object....
           */
          if (!DoShadow(procObject, NULL, METH_PROC_ASSOCIATE,
                                          "My program",
                                          METHOD_END))
             abort_and_cleanse();

          /*
           * Okay, our process is running!
           */

     While this is useful if you want to start with something other than
     a PROCESS_CLASS object, the default PROCESS_CLASS is very useful, and
     a library call can be used instead of this code, which does
     essentially the same thing:

          ShadowBase = OpenLibrary("shadow.library", 5);
          if (!ShadowBase)
             abort_and_cleanse();
          if (!InitOOProgram("My program"))
             abort_and_cleanse();

     Note that we do NOT call CreateInstance() for our process object.
     That, of course, is because we do not want a -new- process, just a
     new SHADOW object to attach to an already existing process....


     Along with METH_PROC_ASSOCIATE, you've also come across
     METH_PROC_HANDLER.  As a default, this is merely the main event loop.
     The main event loop returns when a ^C is sent to the process, however
     messages may continue to get handled even after the ^C is sent so
     that the process can get a shot at deleting its resources....

     Consider, then, the following complex example:
          Process A's handler first sends an asynchronous method to
          process A to, say, draw a random circle.  It then invokes the
          superclass METH_PROC_HANDLER for default message handling.
          Within the draw circle routine is a method invocation that,
          again, invokes an asynchronous method to draw another random
          circle.  Obviously, this executes ad-nauseum.  Now, the
          default handler code is careful about buffering the message
          lists, and therefore allowing the ^C to get processed to start
          the quit sequence of the program, however, because the program
          always has a method waiting for it, it can never shutdown.
          Therefore, your custom handler should also set a global
          variable when the system METH_PROC_HANDLER returns, and the
          circle drawing should note this flag and NOT send another
          asynchronous method when it is sent....

      Fortunately, however, SHADOW already provides such a flag.
      In particular, SHADOW_PROC_FLAGS_REMOVED in ATTR_SHADOWPROCESS'
      sp_flags field is set when the process has returned from the
      HANDLER (or ParseHandlerFrame) routine.   Note that this is not
      set within the METH_PROC_HANDLER method, but is set after the
      routine has exitted by the internal processStartup code....  Thus,
      if you subclass the METH_PROC_HANDLER routine, the flag may or may
      not be set when the superclass' METH_PROC_HANDLER method returns to
      you.  Indeed, as noted, you may even be overriding which method
      call is actually made (via the ParseHandlerFrame).  It is when this
      method returns that the flag is actually set.


      Two more examples for initialization:

          child = CreateInstance(NULL, PROCESS_CLASS,
                                       META_CLASS,
                                       METH_INIT,
                                       "New Process",
                                       CurrentProcess(),
                                         /* Parent process object */
                                       NULL,
                                         /* A NULL semaphore --
                                            strictly speaking, you could
                                            have gotten away with putting
                                            the METHOD_END here, it is
                                            included to remind you that
                                            the parent object is separate from
                                            the semaphore field */
                                       METHOD_END);

          /*
           * Yep!  A new process has started up (assuming child not NULL).
           * We may now use this child in a call to SetupMethodTags() to
           * allow some of our methods to run in the child process.
           */

          success = AddAutoResource(NULL, child, "New Process");
          DropObject(child)
          .
          .
          .

          /*
           * cleanup!
           */
          RemoveCurrentProgram(NULL);
          CloseLibrary(ShadowBase);
          .
          .
          .


     This example shows off how to use the ParseFrames correctly:
     Let's say that you have written a METH_PROC_HANDLER for your
     program's processes in the following fashion:

          ARGUMENT_TAG  REF_HandleMessages[] =
                                {
                                   ARG_STR,
                                   ARG_TAGL(sizeof(struct MethodTag)),
                                   ARG_TAGL(sizeof(struct AttributeTag)),
                                   RET_NORMAL
                                };
          void HandleProcMessages(METHOD_ARGS, char *baseClassName,
                                               char *newModuleClassName,
                                               struct MethodTag *methods,
                                               struct AttributeTag *attrs)
          {
             geta4();    /* Yep, don't forget this! */

             /*
              * Allocate a module class for this process.
              */
             AddAutoResource(NULL, CreateSubClass(NULL,
                                                  baseClassName,
                                                  META_CLASS,
                                                  newModuleClassName,
                                                  NULL,
                                                  methods,
                                                  attrs,
                                                  METHOD_END),
                             newModuleClassName);
             DoSuperShadow(object, class, MethodID, METHOD_END);
          }

     Now, for your own program's process startup, you would naturally use
     something like the following:

          /*
           * Create the process object and attach to the program.
           */
          procClass = FindShadow(MY_PROCESS_CLASS);
          success = DoShadow( DoShadow(procClass,
                                       NULL,
                                       METH_CREATE,
                                       METHOD_END),
                              NULL,
                              METH_PROC_ASSOCIATE,
                              NEW_PROCESS_NAME,
                              METHOD_END);
          DropObject(procClass);

          if (success)
          {
             /*
              * Startup the process and handle all incoming
              * methods.  Also, create my module's class.
              */
             DoShadow(CurrentProcess(), NULL, METH_PROC_HANDLER,
                                              BASE_MODULE_CLASS,
                                              MY_NEW_MODULE_CLASS,
                                              myMethods,
                                              myAttrs,
                                              METHOD_END);
             RemoveCurrentProgram(NULL);
          }

          /*
           * Get out!
           */
          CloseLibrary("shadow.library", 5);
          exit();

     However, this does not solve a bigger problem -- how to create -new-
     processes that are not related to an already existing program-process.
     Obviously, the normal METH_INIT will not work, as the normal
     METH_PROC_HANDLER is called without any arguments.  We can do one of
     two things.  The first crack is to call the METH_INIT in the following
     clumsy fashion:

          struct MyHandlerFrame {
             OBJECT         object;
             META           class;
             char           *MethodID;
             char           *baseClass;
             char           *newClass;
             METHOD_TAG     *methods;
             ATTRIBUTE_TAG  *attrs;
             void           *end;
          } mhf;

          mhf.MethodID = NULL;
          mhf.baseClass = BASE_MODULE_CLASS;
          mhf.newClass = MY_NEW_MODULE_CLASS_2;
          mhf.methods = myMethods_2;
          mhf.attrs = myAttrs_2;
          mhf.end = METHOD_END;

          child = CreateInstance(NULL,
                                 MY_PROCESS_CLASS,
                                 META_CLASS,
                                 METH_INIT,
                                 "New Process #2",
                                 CurrentProcess(),/* Parent process */
                                 NULL,            /* No semaphore   */
                                 NULL,            /* no tags        */
                                 NULL,            /* No InitFrame   */
                                 &mhf

                                 METHOD_END);

     This is clumsy because each time you want to create a new process,
     you also have to setup the MyHandlerFrame.  In addition, because
     the MyHandlerFrame structure has no definitive -length- to it, the
     METH_INIT cannot be called asynchronously.  A much better way is to
     redefine the way you call the METH_INIT for the process as follows:

          /*
           * ProcessClass' METH_INIT
           *
           * NULL if error, else returns the new class-object.
           *
           */
          struct ArgumentTag  REF_InitProcObject[] = {
                                   ARG_STR,
                                   ARG_STR,
                                   ARG_STR,
                                   ARG_TAGL(sizeof(struct MethodTag)),
                                   ARG_TAGL(sizeof(struct AttributeTag)),
                                   RET_OBJ
                                };

          OBJECT InitProcObject(METHOD_ARGS, char *processName,
                                             char *baseClassName,
                                             char *newModuleClassName,
                                             struct MethodTag *methods,
                                             struct AttributeTag *attrs)
          {
             struct MyHandlerFrame {
                OBJECT         object;
                META           class;
                char           *MethodID;
                char           *baseClass;
                char           *newClass;
                METHOD_TAG     *methods;
                ATTRIBUTE_TAG  *attrs;
                void           *end;
             } mhf;

             mhf.MethodID = NULL;  /* default! */
             mhf.baseClass = baseClassName;
             mhf.newClass = newModuleClassName;
             mhf.methods = methods;
             mhf.attrs = attrs;
             mhf.end = METHOD_END;

             /*
              * This method always runs as a callback!
              * So we don't have to worry about resource tracking
              * the variable length HandlerFrame.
              */
             return DoSuperShadow(object, class, MethodID,
                                                 processName,
                                                 CurrentProcess(),
                                                 NULL, NULL, NULL,
                                                 &mhf,
                                                 METHOD_END);
          }

     This is much cleaner, as now to create a new process, all you need to
     do is the following:

          child = CreateInstance(NULL, META_CLASS, MY_PROCESS_CLASS,
                                                   "New Process #3",
                                                   BASE_MODULE_CLASS,
                                                   MY_NEW_MODULE_CLASS_3,
                                                   myMethods_3,
                                                   myAttrs_3,
                                                   METHOD_END);

     This, obviously, looks a lot better, it hides the common code
     in one place, allowing you to easily create new modules that use the
     same master process code without duplicating all of the
     initialization/structure setups....


     Process and Program Shutdown:

     The destruction of a process has similar problems as the
     initialization of processes.  Remember that the destruction of an
     object -already- occurs in two stages -- the REMOVE and then the
     DESTROY.  Unfortunately, the METH_DESTROY method really needs to be
     called as a function, there is, therefore, no guaranteed way to get
     the METH_DESTROY to occur within the process.  The destroy process,
     therefore, has been broken up into two pieces:
          METH_DESTROY -- this sets a DESTROY bit in the ShadowProcess
                          structure and then signals the task with a
                          ^C
          METH_PROC_DISASSOCIATE -- this destroys the ports that were
                                    allocated by SHADOW, and you should
                                    subclass this to destroy/close and
                                    resources you created/opened in the
                                    ASSOCIATE method.  When this method
                                    returns the process' name has also
                                    been freed....  The object's
                                    destruction is completed with magic
                                    that will not be discussed here, but
                                    it is -not- done by the
                                    METH_DISASSOCIATE method.

     Neither of these methods should be called by you, neither do they
     take any arguments.  You may, however, subclass either one of
     them.  For the most part, anything that you would have normally
     put into the the METH_DESTROY you should put into the
     METH_DISASSOCIATE instead....
     By the way, both of these methods methods call the automatic
     cleanup procedure, RemoveResources().  The DISASSOCIATE method
     calls the RemoveResources with the boolean argument set to TRUE,
     whereas both the METH_REMOVE and the METH_DESTROY call
     RemoveResources() with the boolean argument set to FALSE.

     However, process destruction is a two step process, and the first
     step is the METH_REMOVE signal.  The METH_REMOVE sets a REMOVE
     bit in the ShadowProcess flags field (to prevent duplicate
     METH_REMOVE methods) and calls the RemoveResources() call.

     Process shutdown of a program that has been started by the
     InitOOProgram() call, or the CREATE-ASSOCIATE pair of calls,
     needs to be shutdown with the RemoveCurrentProgram() call.  This
     call takes as an argument the optional semaphore that you
     started all of the threads with.  As stated before, the preferred
     manner of starting up is to use the parent process and not a
     global program semaphore -- but the option exists for you to
     consider.  The RemoveCurrentProgram() will not return until it
     is safe for your program to exit.


     METH_FLAG_OBJECT_AS_DEST

     There is a specific method flag to deal with process objects --
     specifically the METH_REMOVE method.  It is completely reasonable
     to wish that a method for a process actually run in that process.
     This is the reason for the METH_FLAG_OBJECT_AS_DEST flag for the
     mtag_flags field of the METHOD_TAG structure.  Specifying the
     METH_FLAG_OBJECT_AS_DEST instead of METH_FLAG_OBJECT or
     METH_CLASS, makes the destination of the method the same as the
     object the method is being invoked on.  In short, invoking a
     method on a process object, where the method is set with the
     METH_OBJECT_AS_DEST flag, forces the method to be run in that
     process object.


                             Initialization Calls

     To recap from the PROCESS_CLASS discussion above, a program is
     initialized and removed in the following fashion under SHADOW:

          if (ShadowBase = OpenLibrary("shadow.library", 5))
          {
             if (InitOOProgram(NEW_PROCESS_NAME))
             {
                /*
                 * Do what you like!
                 * Probably a call to HandleMessages()
                 * HandleMessages() is a macro for:
                 *  DoShadow(CurrentProcess(), NULL, METH_PROC_HANDLER,
                 *                                   METHOD_END);
                 */


                /*
                 * Cleanup!
                 */
                RemoveCurrentProgram(NULL);
             }
             CloseLibrary(ShadowBase);
          }



                                   CONCLUSION



     We have finally come to the end of the "Introduction" to SHADOW.
     We have come quite far during the course of this document.
     Unfortunately, not everything has been covered in the detail
     that it really needs to be.  In order to better understand
     SHADOW, the ShadowLibraryMethods.doc, the ShadowLibraryFuncs.doc,
     and the ShadowLibFuncs.doc are highly recommended.  The introduction
     to ShadowLibraryMethods.doc is recommended regardless.

     In addition, you can browse the basic class descriptions of
     SHADOW using the browser.  In addition, the source to browser,
     though somewhat hacked, is included for your use and perusal.

     If you have understood all of this -- congratulations!  You've done
     better than I would have!  Try and figure out the included sources,
     and contact me with cash for your includes and shadow.lib today!

               David C. Navas
               SHADOW
               7 Avocet Dr. #205
               Redwood Shores, CA 94065

               [e-mail]
               BIX: dnavas